# 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

1. Oracle prompt arrives in current root route.
2. Root builds mission envelope with type `oracle_advisory`.
3. Root persists mission envelope.
4. Root sends mission request to colony service.
5. Colony planner creates task graph.
6. Prompt master creates prompt packages.
7. Librarian prepares root-data route cards.
8. Worker tasks execute against scoped CRM, Oracle, and MCP tools.
9. Aggregator creates answer packet.
10. Reviewer returns reviewed output and optional writeback proposal.
11. 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

1. CRM action selects a lead or cohort.
2. Root creates `crm_lead_intelligence` mission envelope.
3. Root fetches lead and related chat context.
4. Root sends mission envelope to colony.
5. Planner creates tasks for context analysis, optional external research, synthesis, and review.
6. Prompt master creates role-specific packages.
7. Librarian provides scoped passes to leads and chat logs.
8. Researcher provides public market or project evidence only when requested.
9. Worker results are aggregated and reviewed.
10. 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:

```json
{
  "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:

```json
{
  "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

Required:

- mission creation test
- real lead context enrichment test
- chat log usage test
- external research optionality test
- writeback proposal validation test

## 8. Demo and Sales Relevance

These two adapters are the fastest route to a system that supports sales.

Oracle proves:

- strategic advisory
- reviewed synthesis
- structured delivery

CRM proves:

- actionable lead intelligence
- grounded recommendations
- commercial follow-up value

If these two adapters work reliably, Project Velocity can begin demonstrating a real colony orchestration capability rather than only promising one.

## 9. Bottom Line

Oracle and CRM should be built first because they best match the current root state, the architecture design, and the shortest path to revenue-supporting demonstrations.