> ## Documentation Index
> Fetch the complete documentation index at: https://docs.integratewise.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WORKBENCH INTERACTION LIFECYCLE

# Workbench Interaction Lifecycle

> **Version:** 1.0 | **Date:** 2026-08-24 | **Status:** CANONICAL
> **Authority:** Nirmal (Founder)

This document defines the canonical operational model for how the SpineWorkspace workbench enables human-AI collaboration. These are not UI buttons — they are the fundamental operational patterns that define how the system operates.

***

## The Four Operational Patterns

### 1. Store in Spine

All business context, communications, decisions, and evidence are automatically captured into the Spine Fabric. This is the organizational memory that both humans and AI access.

* Data flows from source systems → Spine → available to Twin and workbench
* Every meaningful action returns to Spine
* Spine is the single source of truth (SSOT)
* Memory informs truth; memory is not truth

### 2. Ask Your Twin

Human queries Twin through the workbench. Twin has access to full business context from Spine and provides suggestions, recommendations, and proposals based on that context.

* Bidirectional communication — human can ask, Twin can proactively suggest
* Twin observes the pipeline continuously
* Twin surfaces only when there is material value
* Silence Law: Twin prefers silence over low-value commentary

### 3. Approve Your Twin

Twin's proposals require human authorization for governed actions. Approval triggers the execution flow: capability resolution → governance check → source system write → receipt → reconciliation.

* Human-in-the-Loop (HITL) by design
* Twin NEVER acts without approval
* The user ALWAYS has control
* Governance is a hard gate — no approval token = no execution

### 4. Reject/Redo Your Twin

Human can reject Twin's work. Twin can retry with new context or escalate to human. System reconciles the state — unknown → reconcile → then retry.

* Ensures continuity and prevents hallucinations from cascading
* User can send back for revision
* Twin re-orients with new context
* Loop continues until resolution

***

## The Complete Human-Twin-Agent Flow

```
USER WORKBENCH
      │
      ▼
┌──────────────────────────┐
│  User Action (e.g.,      │
│  Click: "Payment Failure")│  ← Trigger
└──────────┬──────────────┘
           │
           ▼
TWIN OBSERVATION (OODA)
           │
           ├── Observe: User intent + Workbench context
           │
           ├── Orient: Identify domain, user role, urgency
           │
           ├── Decide: This requires context assembly
           │
           └── Act: Initiate Spine query
                   │
                   ▼
SPINE CONTEXT ASSEMBLY
                   │
                   ├── Search canonical spine for entities
                   │   related to the trigger
                   │
                   ├── Assemble: Related entities, history,
                   │   SLA status, business rules
                   │
                   ├── Project: Context + Business rules +
                   │   User permissions
                   │
                   ▼
CONTEXT PROJECTION TO USER
                   │
                   ├── CURRENT STATE
                   │   └── Entity status, metrics, timeline
                   │
                   ├── SUGGESTIONS (Twin-generated)
                   │   ├── Option A: Primary recommendation
                   │   ├── Option B: Alternative approach
                   │   ├── Option C: Escalation path
                   │   └── Option D: Defer/postpone
                   │
                   ├── POSSIBLE ACTIONS
                   │   ├── Action 1: Execute now
                   │   ├── Action 2: Gather more info
                   │   ├── Action 3: Consult stakeholder
                   │   └── Action 4: Approve/reject
                   │
                   ├── ADVERSE EFFECTS (Risk analysis)
                   │   ├── Risk of each option
                   │   ├── Downstream consequences
                   │   ├── Compliance implications
                   │   └── Timeline pressure
                   │
                   └── EVIDENCE
                       ├── Source data references
                       ├── Historical patterns
                       ├── Policy references
                       └── SLA/deadline status
                           │
                           ▼
USER DECISION POINT
                           │
         ┌─────────────────┼─────────────────┐
         ▼                 ▼                 ▼
    [Approve Action]    [Need More Info]   [Consult]
         │                 │                 │
         ▼                 ▼                 ▼
    EXECUTE FLOW      TWIN REFINES       COMMUNICATION
        │                 │                 │
        │                 ▼                 ▼
        │         New Query → Spine    Slack/Chat/Email
        │                 │                 │
        ▼                 ▼                 ▼
   GOVERNED          Updated          Message sent via
   EXECUTION         Projection       connected channel
        │                                 │
        ▼                                 ▼
   Source System               Stakeholder responds
   Write-back                       │
        │                           ▼
        ▼                     USER RECEIVES
   Receipt →                 CONTEXT UPDATE
   Spine Store                    │
        │                         ▼
        ▼                     USER DECIDES
   Continuity                   (loop or new path)
```

***

## Learning & Adaptation Layer

The system learns from user behavior and adapts over time:

### Spine Memory Updates

* User clicked "Payment Failure" → Tag as high-priority pattern
* User selected "Contact Customer" → Learn preference for this error type
* User consulted Slack #finance-team → Map as escalation path
* Boss approved write-off → Store as delegated authority

### Twin Adaptation

* Next similar failure → Propose "Contact Customer" first
* Detect urgency → Auto-suggest escalation path
* Recognize user → Pre-load their common actions
* Domain learning → Finance payment workflows

***

## External Tool Integration Flow

When an action requires an external system, Twin routes to the appropriate integration method:

### API Direct Call (REST/GraphQL)

* Capability: Specific operation (e.g., "Retry Payment")
* Endpoint: Target API endpoint
* Auth: OAuth2 via One Auth
* Write-back: Spine receives receipt

### MCP Server (Model Context Protocol)

* Tool: Specific MCP tool (e.g., `stripe.get_payment_intent`)
* Resource: MCP resource URI
* Context: Full Spine context passed
* Return: Structured data → Spine normalization

### Spine Tools (Internal connectors)

* Pre-built: Salesforce, HubSpot, Slack, etc.
* Custom: Customer-specific integrations
* ADK: Agent Development Kit for custom tools

### Orchestrator (Complex workflows)

* Multi-step: Check credit → Retry → Notify → Log
* Agent delegation: Specialized agent handles logic
* Coordination: Multiple agents + tools
* Handoff: Results return to Twin for final report

***

## Agent Communication & Work Transfer

### Agent Network Operation

```
Twin (Orchestrator)
    │
    ├── Receives: User request + Spine context
    ├── Analyzes: Intent, domain, required capabilities
    ├── Decides: Can handle directly OR delegate
    │
    └── DELEGATION PATH:
        │
        ├── Simple query → Twin handles directly
        │
        ├── Domain-specific → Domain Agent
        │      │
        │      ├── Receives: Context subset relevant to domain
        │      ├── Executes: Domain-specific logic
        │      └── Returns: Result + evidence to Twin
        │
        └── Complex research → Research Agent
               │
               ├── Multi-source: Check CRM, support, email
               ├── Pattern match: Similar past cases
               └── Returns: Analysis to Twin for synthesis
```

### Work Transfer Protocol

1. Agent → Twin: Structured result + evidence bundle
2. Twin validates: Against Spine context + user intent
3. Twin enriches: Adds user-specific context
4. Twin reports: Final answer to user in workbench

***

## Final Report Structure

When Twin reports back to user, the report includes:

```markdown theme={null}
## [Issue/Task] - Resolution Summary

**Status**: RESOLVED | PENDING | ESCALATED
**Action Taken**: [Description of action]
**Result**: [Outcome]

**What Happened**:
- [Root cause]
- [Steps taken]
- [Resolution]

**Actions Executed**:
1. [Action 1] - Status
2. [Action 2] - Status
3. [Action 3] - Status

**Evidence**:
- [Source reference 1]
- [Source reference 2]
- [Spine event reference]

**Recommendations**:
- [Follow-up item 1]
- [Follow-up item 2]

**Next Steps**:
- [ ] [Action item 1]
- [ ] [Action item 2]
```

***

## The Three-Tier Operational Model

| Layer              | Responsibility                      | Interaction                     |
| ------------------ | ----------------------------------- | ------------------------------- |
| **User Workbench** | Decision making, approval           | Clicks, views, decides          |
| **Twin**           | Observation, orchestration, context | OODA loop, delegates to agents  |
| **Spine Fabric**   | Memory, context, continuity         | Stores everything, connects all |
| **Agents**         | Specialized execution               | Tools, APIs, MCP, research      |
| **Source Systems** | Transaction processing              | Write-back via connectors       |

***

## Key Principles

1. **Human stays in control** — Twin NEVER acts without approval
2. **Twin learns and adapts** — Spine memory informs future proposals
3. **Spine is the single source of truth** — Everything flows back to Spine
4. **Agents handle complexity** — Specialized execution, delegated by Twin
5. **Full transparency** — Every action, decision, and result is recorded

***

## Relationship to OODA Grammar

The Four Operational Patterns map directly to the OODA control grammar:

| Operational Pattern   | OODA Phase  | Button                |
| --------------------- | ----------- | --------------------- |
| Store in Spine        | **Observe** | Store in Spine        |
| Ask Your Twin         | **Orient**  | Ask your Twin         |
| Approve Your Twin     | **Decide**  | Assign your Twin      |
| Reject/Redo Your Twin | **Act**     | Approve Twin's Action |

The OODA Grammar is the control language. The Operational Patterns are how the workbench manifests that language in daily work.