293 lines
7.1 KiB
Markdown
293 lines
7.1 KiB
Markdown
# 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.
|