{"slug":"architecture/WORKBENCH_CANONICAL_MODEL","title":"Workbench Canonical Model","section":"architecture","sectionLabel":"Architecture","status":"canon","type":"document","path":"architecture/WORKBENCH_CANONICAL_MODEL.mdx","bytes":12687,"description":null,"updated":"2026-08-24","source":"integratewise/Integratewise-docs-wiki","content":"\n\nThe dictated target model for the adaptive (Spine) Workbench: one surface where context is\nassembled and gathered for the user, organized by four canonical sidebar sections, powered by\nthe Spine schema, projected per role/domain, and worked by Human + Twin + Coworker together.\n\nEvidence labels follow `_reference_ARCHITECTURE_v3.1.md`: **LAW**, **VERIFIED**, **INTENDED**, **DRIFT**.\n\n---\n\n## 1. The One-Surface Law\n\n> The Workbench is ONE surface. There are no layers, modes, or alternate UIs.\n> L-labels never appear in user-facing UI.\n\n**LAW.** Reaffirmed from ARCHITECTURE_LOCK §V and v3.1 Projection Law.\n\n## 2. Left Sidebar — Four Canonical Sections\n\n| #   | Section                 | Contents                                                                                                                                     | Purpose                                                   |\n| --- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |\n| 1   | **Today**               | Personal/day view — what needs to be taken care of today                                                                                     | Daily orientation; the entry point of the User Path       |\n| 2   | **Communications**      | Teams-style messaging: email, chat, calls, meetings, shared documents                                                                        | Human↔human continuity inside the same surface            |\n| 3   | **Organization Memory** | Organizational calls, decisions, and documentation for the work and the work environment — a Notion-like knowledge workspace over org memory | Shared institutional knowledge; reads governed org memory |\n| 4   | **Work**                | Complete business-context views — role/domain projections of Spine data                                                                      | The operational surfaces where work is done               |\n\n### Current implementation vs model\n\n| Section             | Status             | Where                                                                                                            |\n| ------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------- |\n| Today               | **VERIFIED**       | `home` + `personal` nav groups (`packages/workbench-config/src/generated/navigation.ts`)                         |\n| Communications      | **VERIFIED**       | `communications` group — Email, Calendar, Meetings, Chat, Calls, Documents, Activity                             |\n| Organization Memory | **INTENDED — GAP** | Only personal-scope Knowledge Base/Notes exist under `personal`; an org-scoped Memory section does not yet exist |\n| Work                | **VERIFIED**       | `my-work` group, re-keyed per role via `resolveWorkNavigationForRole`                                            |\n\n## 3. Spine Schema Generator\n\n**INTENDED.**\n\nThe Spine schema is generated for organizational needs from the **organizational lifecycle of\nevents** — not hand-authored per customer. The generator derives entity types, relationships,\nevent types, and memory scopes from how the organization actually operates.\n\n```\nOrganizational lifecycle events\n        ↓\n   SPINE SCHEMA GENERATOR\n        ↓\nCanonical schema (entities · relations · events · memory scopes)\n        ↓\nPer-role / per-domain PROJECTIONS\n```\n\n- Schema generation is a System Path concern. Users never see or configure raw schemas.\n- Generated schema feeds both the Workbench projections and the AI Operational Sandbox assembly.\n- Alignment: v3.1 Store ownership (canonical vs operational) and Loader Runtime ingestion.\n\n## 4. Projections — Same Data, Per-Role Views\n\n**LAW (Projection Law).** Every user sees the SAME organizational data through their OWN view,\nscoped by RBAC, role, and domain.\n\n- A projection is a view of shared truth — never a new source of truth.\n- Cross-team and cross-domain collaboration happens by sharing knowledge ON the Spine — not by\n  copying data between teams.\n- 15 external domain workbenches + 3 internal surfaces already encode this:\n  `packages/workbench-config/src/domain-workbenches.ts` (**VERIFIED**).\n- AI enables the work on these projections: workflows, agents, intelligence operate against the\n  projection scope, promoting proposals through governance when they must become canonical.\n\n## 5. Twin — The User's Digital Twin\n\n**Refinement of v3.1 Twin Law.**\n\n- Each user receives exactly ONE Twin, allotted to the domain of the user's role.\n  The Twin does NOT need to cover vast domains — its own user's domain plus that domain's agents\n  and domain workspaces are enough. **INTENDED**\n- The Twin is the user's digital assistant/agent for their work: it carries out digital and\n  agentic executions end-to-end.\n- It operates ONLY on sandbox (operational) data — never canonical Spine. **LAW (AI Sandbox Law)**\n\n### Shared Task Assignment Layer\n\n**INTENDED — key new contract.**\n\nA single task layer spans human and agents:\n\n```\nTask assigned ──→ [ SHARED TASK LAYER ] ──→ human OR agent\n                        │\n                  Twin orchestrates:\n                  takes tasks from the layer,\n                  allots subtasks to domain agents,\n                  drives them to completion,\n                  returns results to the layer\n```\n\n- Tasks may be allotted to the user, to agents, or to user+agent jointly.\n- The Twin is the orchestrator within this layer; it delegates to domain-specific agents.\n- Every allotment and completion is visible to the user in the Workbench (no hidden execution).\n- Governed effects still traverse Governance → Execution Fabric. The task layer coordinates;\n  it does not authorize.\n\n### Twin Workbench (Agentic Home)\n\n**INTENDED.**\n\nThe Twin has its own workspace — a home base for agentic work (conceptually like Open WebUI /\nLangChain): sessions, tool use, agent roster, running executions — all operating on the sandbox\ncopy of context. The Agent Workspace is SEPARATE from the User Workbench; the two stay\nconsistent through the platform loop, not through shared state.\n\n## 6. Coworker — Context Companion\n\nPer v3.1 Coworker Law, now made concrete:\n\n- Gathers context from the user's screen — active work surface and interaction with the\n  Workbench. **INTENDED**\n- Feeds assembled context to Twin and pipeline executions.\n- Handles communications in CONSISTENCY with the Twin — one voice to the outside, two roles\n  inside: Coworker = context + communication; Twin = reasoning + delegation. **INTENDED**\n- Neither is a second authority. Neither writes canonical truth.\n\n## 7. The Full Drill-Down Loop\n\n```\nORGANIZATIONAL NEEDS  (scattered across multiple tools & software)\n        │\n        ▼\nSOURCE TOOLS converge into\nSPINE FABRIC           (contextual layer for business continuity)\n        │\n        ├──────────────► serves HUMAN  → projections → USER WORKBENCH\n        │\n        └───(sandbox only)──► serves AI  → TWIN WORKBENCH (agentic home)\n                                │              │\n                                │        shared TASK LAYER\n                                │        (human ⇄ agents, Twin orchestrates)\n                                ▼\n                          WORK EXECUTED & COMPLETED\n                                │\n                                ▼\n                     results WRITE BACK to SOURCE TOOLS\n                     via workflows — driven by AI, not manual repetition\n                                │\n                                ▼\n                    PLATFORM UNDERNEATH carries everything:\n                    auth · packages · MCP connectors · infrastructure\n                    pipeline · loop · communication layer · ADK · orchestrator\n                    (communication enablers; can talk to other platforms too)\n```\n\nKey distinctions:\n\n| Distinction                       | Rule                                                                                          |\n| --------------------------------- | --------------------------------------------------------------------------------------------- |\n| Canonical Spine                   | Humans reach it through projections; **AI NEVER touches it** — sandbox only                   |\n| User Workbench vs Agent Workspace | Two separate surfaces, kept consistent by the platform loop                                   |\n| Task execution                    | AI-driven write-back into source tools via workflows — humans stop doing monotonous sync work |\n| Platform                          | Enabler only. It never becomes a second Workbench (Platform Law)                              |\n\n## 8. Layer Model\n\n1. **Organization layer** — decides goals and needs.\n2. **Cascade layer** — goals/needs transfer to humans by domain, role, responsibility.\n3. **Human layer** — works tasks/goals aligned to organizational and business needs.\n4. **AI layer (per-user instance)** — ONE Twin per user, scoped to the user's role domain;\n   domain agents + domain workspaces attached; no vast cross-domain coverage required.\n5. **Surfaces layer** — User Workbench (projections) separate from Agent Workspace (Twin home).\n6. **Platform layer** — pipeline, loop, communication layer, MCP, ADK, orchestrator:\n   communication channels and enablers underneath everything.\n\n## 9. Boundary Laws (restated for this model)\n\n- **AI Sandbox Law** — AI reads sandbox, never canonical Spine.\n- **Governance Law** — confidence never grants authority; consequential mutation passes\n  Governance before Execution Fabric.\n- **Projection Law** — projections are views, not sources.\n- **Platform Law** — the substrate enables; it does not become another Workbench.\n- **Continuity Law** — bounded continuity across people, tools, AI hosts, domains.\n\n## 10. Gap Register — Dictated Model vs Current Code\n\n| #   | Model element                                                        | State                                                       | Next step                                                                                                   |\n| --- | -------------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |\n| G1  | Organization Memory sidebar section (org-scoped knowledge workspace) | INTENDED — GAP                                              | Promote personal Knowledge Base patterns into an org-memory-backed section reading approved org_memory only |\n| G2  | Spine Schema Generator from org lifecycle events                     | INTENDED                                                    | Spec + service boundary in Pipeline plane                                                                   |\n| G3  | Shared Task Assignment Layer (human ⇄ agents)                        | INTENDED                                                    | Extend Task Management MCP contracts with assignee-kind (human/agent/joint) + Twin orchestration hooks      |\n| G4  | Twin Workbench as separate agentic home                              | PARTIAL — Twin runtime exists (`services/iw-agent-runtime`) | Productize session/tool/agent-roster surface                                                                |\n| G5  | One-Twin-per-user scoped to role domain                              | PARTIAL — Twin binding exists                               | Enforce 1:1 user:Twin allotment with domain scoping in runtime config                                       |\n| G6  | Coworker screen-context gathering + unified comms with Twin          | INTENDED                                                    | New Coworker capability in runtime; comms consistency contract                                              |\n| G7  | AI-driven write-back of completed work into source tools             | PARTIAL — reconciliation loop exists in doctrine            | Wire workflow-based writeback into Execution Fabric outcomes                                                |\n"}