{"slug":"architecture/WORKBENCH_INTERACTION_LIFECYCLE","title":"Workbench Interaction Lifecycle","section":"architecture","sectionLabel":"Architecture","status":"unclassified","type":"document","path":"architecture/WORKBENCH_INTERACTION_LIFECYCLE.mdx","bytes":10803,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n> **Version:** 1.0 | **Date:** 2026-08-24 | **Status:** CANONICAL\n> **Authority:** Nirmal (Founder)\n\nThis document defines the canonical operational model for how the Spine Workspace workbench enables human-AI collaboration. These are not UI buttons — they are the fundamental operational patterns that define how the system operates.\n\n---\n\n## The Four Operational Patterns\n\n### 1. Store in Spine\n\nAll business context, communications, decisions, and evidence are automatically captured into the Spine Fabric. This is the organizational memory that both humans and AI access.\n\n- Data flows from source systems → Spine → available to Twin and workbench\n- Every meaningful action returns to Spine\n- Spine is the single source of truth (SSOT)\n- Memory informs truth; memory is not truth\n\n### 2. Ask Your Twin\n\nHuman queries Twin through the workbench. Twin has access to full business context from Spine and provides suggestions, recommendations, and proposals based on that context.\n\n- Bidirectional communication — human can ask, Twin can proactively suggest\n- Twin observes the pipeline continuously\n- Twin surfaces only when there is material value\n- Silence Law: Twin prefers silence over low-value commentary\n\n### 3. Approve Your Twin\n\nTwin's proposals require human authorization for governed actions. Approval triggers the execution flow: capability resolution → governance check → source system write → receipt → reconciliation.\n\n- Human-in-the-Loop (HITL) by design\n- Twin NEVER acts without approval\n- The user ALWAYS has control\n- Governance is a hard gate — no approval token = no execution\n\n### 4. Reject/Redo Your Twin\n\nHuman can reject Twin's work. Twin can retry with new context or escalate to human. System reconciles the state — unknown → reconcile → then retry.\n\n- Ensures continuity and prevents hallucinations from cascading\n- User can send back for revision\n- Twin re-orients with new context\n- Loop continues until resolution\n\n---\n\n## The Complete Human-Twin-Agent Flow\n\n```\nUSER WORKBENCH\n      │\n      ▼\n┌──────────────────────────┐\n│  User Action (e.g.,      │\n│  Click: \"Payment Failure\")│  ← Trigger\n└──────────┬──────────────┘\n           │\n           ▼\nTWIN OBSERVATION (OODA)\n           │\n           ├── Observe: User intent + Workbench context\n           │\n           ├── Orient: Identify domain, user role, urgency\n           │\n           ├── Decide: This requires context assembly\n           │\n           └── Act: Initiate Spine query\n                   │\n                   ▼\nSPINE CONTEXT ASSEMBLY\n                   │\n                   ├── Search canonical spine for entities\n                   │   related to the trigger\n                   │\n                   ├── Assemble: Related entities, history,\n                   │   SLA status, business rules\n                   │\n                   ├── Project: Context + Business rules +\n                   │   User permissions\n                   │\n                   ▼\nCONTEXT PROJECTION TO USER\n                   │\n                   ├── CURRENT STATE\n                   │   └── Entity status, metrics, timeline\n                   │\n                   ├── SUGGESTIONS (Twin-generated)\n                   │   ├── Option A: Primary recommendation\n                   │   ├── Option B: Alternative approach\n                   │   ├── Option C: Escalation path\n                   │   └── Option D: Defer/postpone\n                   │\n                   ├── POSSIBLE ACTIONS\n                   │   ├── Action 1: Execute now\n                   │   ├── Action 2: Gather more info\n                   │   ├── Action 3: Consult stakeholder\n                   │   └── Action 4: Approve/reject\n                   │\n                   ├── ADVERSE EFFECTS (Risk analysis)\n                   │   ├── Risk of each option\n                   │   ├── Downstream consequences\n                   │   ├── Compliance implications\n                   │   └── Timeline pressure\n                   │\n                   └── EVIDENCE\n                       ├── Source data references\n                       ├── Historical patterns\n                       ├── Policy references\n                       └── SLA/deadline status\n                           │\n                           ▼\nUSER DECISION POINT\n                           │\n         ┌─────────────────┼─────────────────┐\n         ▼                 ▼                 ▼\n    [Approve Action]    [Need More Info]   [Consult]\n         │                 │                 │\n         ▼                 ▼                 ▼\n    EXECUTE FLOW      TWIN REFINES       COMMUNICATION\n        │                 │                 │\n        │                 ▼                 ▼\n        │         New Query → Spine    Slack/Chat/Email\n        │                 │                 │\n        ▼                 ▼                 ▼\n   GOVERNED          Updated          Message sent via\n   EXECUTION         Projection       connected channel\n        │                                 │\n        ▼                                 ▼\n   Source System               Stakeholder responds\n   Write-back                       │\n        │                           ▼\n        ▼                     USER RECEIVES\n   Receipt →                 CONTEXT UPDATE\n   Spine Store                    │\n        │                         ▼\n        ▼                     USER DECIDES\n   Continuity                   (loop or new path)\n```\n\n---\n\n## Learning & Adaptation Layer\n\nThe system learns from user behavior and adapts over time:\n\n### Spine Memory Updates\n\n- User clicked \"Payment Failure\" → Tag as high-priority pattern\n- User selected \"Contact Customer\" → Learn preference for this error type\n- User consulted Slack #finance-team → Map as escalation path\n- Boss approved write-off → Store as delegated authority\n\n### Twin Adaptation\n\n- Next similar failure → Propose \"Contact Customer\" first\n- Detect urgency → Auto-suggest escalation path\n- Recognize user → Pre-load their common actions\n- Domain learning → Finance payment workflows\n\n---\n\n## External Tool Integration Flow\n\nWhen an action requires an external system, Twin routes to the appropriate integration method:\n\n### API Direct Call (REST/GraphQL)\n\n- Capability: Specific operation (e.g., \"Retry Payment\")\n- Endpoint: Target API endpoint\n- Auth: OAuth2 via One Auth\n- Write-back: Spine receives receipt\n\n### MCP Server (Model Context Protocol)\n\n- Tool: Specific MCP tool (e.g., `stripe.get_payment_intent`)\n- Resource: MCP resource URI\n- Context: Full Spine context passed\n- Return: Structured data → Spine normalization\n\n### Spine Tools (Internal connectors)\n\n- Pre-built: Salesforce, HubSpot, Slack, etc.\n- Custom: Customer-specific integrations\n- ADK: Agent Development Kit for custom tools\n\n### Orchestrator (Complex workflows)\n\n- Multi-step: Check credit → Retry → Notify → Log\n- Agent delegation: Specialized agent handles logic\n- Coordination: Multiple agents + tools\n- Handoff: Results return to Twin for final report\n\n---\n\n## Agent Communication & Work Transfer\n\n### Agent Network Operation\n\n```\nTwin (Orchestrator)\n    │\n    ├── Receives: User request + Spine context\n    ├── Analyzes: Intent, domain, required capabilities\n    ├── Decides: Can handle directly OR delegate\n    │\n    └── DELEGATION PATH:\n        │\n        ├── Simple query → Twin handles directly\n        │\n        ├── Domain-specific → Domain Agent\n        │      │\n        │      ├── Receives: Context subset relevant to domain\n        │      ├── Executes: Domain-specific logic\n        │      └── Returns: Result + evidence to Twin\n        │\n        └── Complex research → Research Agent\n               │\n               ├── Multi-source: Check CRM, support, email\n               ├── Pattern match: Similar past cases\n               └── Returns: Analysis to Twin for synthesis\n```\n\n### Work Transfer Protocol\n\n1. Agent → Twin: Structured result + evidence bundle\n2. Twin validates: Against Spine context + user intent\n3. Twin enriches: Adds user-specific context\n4. Twin reports: Final answer to user in workbench\n\n---\n\n## Final Report Structure\n\nWhen Twin reports back to user, the report includes:\n\n```markdown\n## [Issue/Task] - Resolution Summary\n\n**Status**: RESOLVED | PENDING | ESCALATED\n**Action Taken**: [Description of action]\n**Result**: [Outcome]\n\n**What Happened**:\n- [Root cause]\n- [Steps taken]\n- [Resolution]\n\n**Actions Executed**:\n1. [Action 1] - Status\n2. [Action 2] - Status\n3. [Action 3] - Status\n\n**Evidence**:\n- [Source reference 1]\n- [Source reference 2]\n- [Spine event reference]\n\n**Recommendations**:\n- [Follow-up item 1]\n- [Follow-up item 2]\n\n**Next Steps**:\n- [ ] [Action item 1]\n- [ ] [Action item 2]\n```\n\n---\n\n## The Three-Tier Operational Model\n\n| Layer | Responsibility | Interaction |\n|-------|---------------|-------------|\n| **User Workbench** | Decision making, approval | Clicks, views, decides |\n| **Twin** | Observation, orchestration, context | OODA loop, delegates to agents |\n| **Spine Fabric** | Memory, context, continuity | Stores everything, connects all |\n| **Agents** | Specialized execution | Tools, APIs, MCP, research |\n| **Source Systems** | Transaction processing | Write-back via connectors |\n\n---\n\n## Key Principles\n\n1. **Human stays in control** — Twin NEVER acts without approval\n2. **Twin learns and adapts** — Spine memory informs future proposals\n3. **Spine is the single source of truth** — Everything flows back to Spine\n4. **Agents handle complexity** — Specialized execution, delegated by Twin\n5. **Full transparency** — Every action, decision, and result is recorded\n\n---\n\n## Relationship to OODA Grammar\n\nThe Four Operational Patterns map directly to the OODA control grammar:\n\n| Operational Pattern | OODA Phase | Button |\n|--------------------|------------|--------|\n| Store in Spine | **Observe** | Store in Spine |\n| Ask Your Twin | **Orient** | Ask your Twin |\n| Approve Your Twin | **Decide** | Assign your Twin |\n| Reject/Redo Your Twin | **Act** | Approve Twin's Action |\n\nThe OODA Grammar is the control language. The Operational Patterns are how the workbench manifests that language in daily work.\n"}