{"slug":"architecture/TWIN","title":"Twin — AI Workspace","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/TWIN.mdx","bytes":5195,"description":"The user's AI work partner — one Twin per user, shared task assignment layer, operating within bounded context.","updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nTwin is the user's AI work partner. Each user has **one primary Twin** that operates as their work coordinator, digital execution coordinator, and orchestration boundary.\n\nTwin is not a panel, layer, or sidebar destination. Twin is a **capability of the Workbench** that surfaces contextually via the Four Buttons.\n\n## Twin Operating Model\n\n```text\nUNDERSTAND\n  ↓\nCONTEXTUALIZE\n  ↓\nTRIAGE\n  ↓\nALLOCATE\n  ↓\nPLAN / PROPOSE\n  ↓\nDELEGATE\n  ↓\nEXECUTE\n  ↓\nVERIFY\n  ↓\nREPORT\n  ↓\nADAPT\n```\n\nInternal reasoning follows OODA:\n\n```text\nOBSERVE → ORIENT → DECIDE → ACT\n```\n\n## One Twin Per User\n\nEach user has exactly one Twin. The Twin is:\n\n- Scoped to the user's role domain\n- Aware of the user's work context\n- Connected to the user's organizational memory\n- Bounded by the user's permissions and authority\n\nThe Twin is NOT:\n- Unrestricted enterprise authority\n- A second source of truth\n- A replacement for governance\n- A standalone product surface\n\n## Shared Task Assignment Layer\n\nTwin and humans share a task assignment layer. This layer:\n\n- Receives work from multiple sources (human assignment, system events, agent proposals)\n- Routes work based on capability, availability, and policy\n- Tracks assignment state across sessions\n- Supports handoff between human and AI\n\n```text\nWORK SOURCES\n    ├── Human assigns to self\n    ├── Human assigns to Twin\n    ├── System event generates work\n    ├── Agent proposes work\n    └── Workflow generates work\n          ↓\nSHARED TASK ASSIGNMENT LAYER\n          ↓\nCAPABILITY-BASED ROUTING\n          ↓\nEXECUTION\n```\n\n## Context Assembly + AI Sandbox\n\nTwin operates within bounded context assembled from Spine Fabric:\n\n```text\nCANONICAL SPINE\n      ↓\nCONTEXT ASSEMBLY\n      ├── Permission (what Twin may see)\n      ├── Purpose (why Twin needs this context)\n      ├── Relevance (what is related to current work)\n      └── Freshness (how current is this context)\n      ↓\nAI OPERATIONAL SANDBOX\n      ↓\nTWIN REASONING\n```\n\n**Rules:**\n- Canonical Spine is never directly exposed to AI\n- Context assembly is bounded by permission, purpose, relevance, freshness\n- AI operates only within the operational sandbox\n- Twin consumes projected context, not raw Spine\n\n## Twin Modes\n\n### Passive Mode — Always Observe, Stay Lightweight\n\nTwin continuously observes without continuously performing expensive reasoning:\n\n- Pipeline events\n- Spine changes\n- Current Workbench surface\n- Current entity\n- User actions\n- OODA state\n- Approvals and outcomes\n\nOnly material signals produce lightweight surfacing:\n- \"Renewal risk detected.\"\n- \"Meeting starts in 10 minutes.\"\n- \"Three approvals pending.\"\n\n### Active Mode — Ask your Twin\n\nWhen the user clicks **Ask your Twin**, Twin escalates from observation to grounded reasoning:\n\n```text\nAsk your Twin\n    ↓\nORIENT\n    ├── Current Workbench surface\n    ├── Current entity and related entities\n    ├── Spine projection, timeline, relationships, provenance\n    ├── Pipeline state, freshness, ingestion status\n    ├── OODA state\n    ├── Evidence and connected-system context\n    └── Organizational memory\n    ↓\nTHINK\n    ↓\nEvidence-backed recommendation\n    ↓\nUser decides\n```\n\n## Four Buttons (OODA Grammar)\n\nThe Four Buttons are the explicit human-to-platform control grammar:\n\n| Button | OODA Phase | User Intent | Platform Behavior |\n|--------|-----------|-------------|-------------------|\n| **Store in Spine** | Observe | Capture durable observation | Governed write through Pipeline |\n| **Ask your Twin** | Orient | Request understanding | Twin reads bounded context, reasons |\n| **Assign your Twin** | Decide | Delegate bounded task | Twin creates draft/proposal from context |\n| **Approve Twin's Action** | Act | Authorize proposal | Governance validates, Pipeline executes |\n\n## Grounded Twin Inputs\n\nEvery Twin response is grounded in bounded context:\n\n```text\nCurrent Surface\n    + Current Entity\n    + Pipeline State\n    + OODA State\n    + Adaptive Spine\n    + Evidence\n    + Connected Systems\n    + Organizational Memory\n    ↓\nTwin Reasoning\n```\n\nTwin must distinguish facts, evidence, freshness, uncertainty, and recommendations. It never invents missing operational truth.\n\n## Twin Lifecycle\n\n```text\nINITIALIZE → OBSERVE → ORIENT → PROPOSE → WAIT → EXECUTE → VERIFY → REPORT\n     ↓          ↓         ↓         ↓        ↓        ↓         ↓        ↓\n  Load      Passive   Context   Draft    Human    Governed  Check    Update\n  context   mode      assembly  proposal decides  execution outcome  Spine\n```\n\n## Related\n\n- [Workbench Canonical Model](/architecture/WORKBENCH_CANONICAL_MODEL) — the surface Twin operates on\n- [Agent Fabric](/architecture/AGENT_FABRIC) — the agent fleet Twin orchestrates\n- [Governance](/architecture/GOVERNANCE) — the policy boundary Twin respects\n- [Work Graph](/architecture/WORK_GRAPH) — the work Twin allocates\n"}