Files

Sagnik 4b21c2cad6 feat: Oracle CRM Page, Synthetic Client Data and Live Snapshot when hitting emotion hotpoint

2026-04-19 00:43:01 +05:30

7.1 KiB

Raw Blame History

Oracle and CRM Adapter Detailed Implementation Spec

Date: 2026-04-14
Status: Draft implementation artifact
Purpose: Define the exact adapter behavior, request and response contracts, file placements, runtime flow, and acceptance criteria for the two first colony mission consumers: Oracle and CRM.

1. Purpose

Oracle and CRM are the first two adapters because they already have the strongest root primitives and the clearest near-term business value.

2. Adapter Strategy

The adapters must not bypass current root ownership. They are translation layers between:

current Project Velocity product surfaces
the new colony runtime

The adapters are therefore integration boundaries, not new domain roots.

3. Oracle Adapter Spec

3.1 Oracle Mission Type

Primary Phase 1 mission type:

oracle_advisory

3.2 Oracle Entry Points

The adapter should be callable from:

Oracle helper routes under backend/api/routes_oracle.py
Oracle v1 prompt submission flow under backend/oracle/router_v1.py

3.3 Oracle Context Inputs

Oracle mission creation should include:

tenant_id
actor_id
actor_role
page_id
branch_id
prompt
conversation_context
optional target_lead_id

3.4 Oracle Adapter File Placement

TypeScript:

services/colony-orchestrator/src/adapters/oracle-adapter.ts

Python root:

backend/services/colony_gateway.py
backend/api/routes_colony.py
adapter-specific entry hook in backend/api/routes_oracle.py

3.5 Oracle Mission Creation Flow

Oracle prompt arrives in current root route.
Root builds mission envelope with type oracle_advisory.
Root persists mission envelope.
Root sends mission request to colony service.
Colony planner creates task graph.
Prompt master creates prompt packages.
Librarian prepares root-data route cards.
Worker tasks execute against scoped CRM, Oracle, and MCP tools.
Aggregator creates answer packet.
Reviewer returns reviewed output and optional writeback proposal.
Root returns reviewed packet to Oracle UI.

3.6 Oracle Output Contract

The reviewed Oracle response should include:

final summary text
structured sections for renderable Oracle use
citations or internal references where applicable
optional writeback_proposal
mission metadata

3.7 Oracle Writeback Rules

Oracle adapter may propose:

lead note update
lead score update
lead stage update
Oracle action creation

Oracle adapter may not directly commit these changes from colony workers. All mutations must pass through root writeback policy.

3.8 Oracle Acceptance Criteria

Oracle adapter is complete for Sprint 1 when:

a live Oracle prompt can create a mission
the mission returns a reviewed response
the response references real root data
a writeback proposal can be generated
no regression occurs in existing Oracle v1 canvas behavior

4. CRM Adapter Spec

4.1 CRM Mission Type

Primary Phase 1 mission type:

crm_lead_intelligence

4.2 CRM Entry Points

The adapter should be callable from:

new colony routes
CRM UI actions triggered from pipeline, lead inspector, or dashboard surfaces

4.3 CRM Context Inputs

CRM mission creation should include:

tenant_id
actor_id
actor_role
lead_id
optional kanban_status
optional query_focus
optional include_external_research

4.4 CRM Adapter File Placement

TypeScript:

services/colony-orchestrator/src/adapters/crm-adapter.ts

Python root:

backend/services/colony_gateway.py
backend/api/routes_colony.py
optional helper integration in backend/api/routes_crm.py

4.5 CRM Mission Creation Flow

CRM action selects a lead or cohort.
Root creates crm_lead_intelligence mission envelope.
Root fetches lead and related chat context.
Root sends mission envelope to colony.
Planner creates tasks for context analysis, optional external research, synthesis, and review.
Prompt master creates role-specific packages.
Librarian provides scoped passes to leads and chat logs.
Researcher provides public market or project evidence only when requested.
Worker results are aggregated and reviewed.
Root returns structured CRM guidance to UI.

4.6 CRM Output Contract

Reviewed CRM output should include:

lead priority assessment
intent summary
recommended next step
message draft suggestions
risk flags
optional writeback proposal

4.7 CRM Writeback Rules

CRM adapter may propose:

lead stage move
lead note append
lead qualification update
follow-up task creation

CRM adapter may not directly write these changes from colony workers.

4.8 CRM Acceptance Criteria

CRM adapter is complete for Sprint 1 when:

one lead mission runs end to end
reviewed output uses real lead and chat data
output includes actionable next-step suggestions
optional writeback proposal is generated safely
existing CRM routes continue to function unchanged

5. Shared Adapter Contracts

5.1 Root Request Shape

Both adapters should submit missions to root in a shape like:

{
  "mission_type": "oracle_advisory",
  "origin_surface": "oracle",
  "tenant_id": "tenant_velocity",
  "actor_id": "oracle_operator",
  "actor_role": "sales_director",
  "user_goal": "Original operator prompt",
  "context_refs": {
    "lead_ids": ["lead_123"],
    "page_id": "page_abc",
    "branch_id": "main"
  }
}

5.2 Root Response Shape

Both adapters should receive:

{
  "mission_id": "uuid",
  "status": "completed",
  "review_status": "approved_with_edits",
  "final_output": {},
  "writeback_proposal": null,
  "trace_summary": {
    "task_count": 5,
    "duration_ms": 12850
  }
}

6. Adapter-Specific Files to Modify

6.1 Python Files

Create or modify:

backend/api/routes_colony.py
backend/services/colony_gateway.py
backend/services/colony_repository.py
backend/main.py
backend/api/routes_oracle.py
backend/api/routes_crm.py

6.2 TypeScript Files

Create:

services/colony-orchestrator/src/adapters/oracle-adapter.ts
services/colony-orchestrator/src/adapters/crm-adapter.ts
services/colony-orchestrator/src/adapters/python-root-client.ts

7. Test Plan

7.1 Oracle Adapter Tests

Required:

mission creation test
mission status retrieval test
reviewed output shape test
writeback proposal validation test
Oracle regression test

7.2 CRM Adapter Tests