feat: Oracle CRM Page, Synthetic Client Data and Live Snapshot when hitting emotion hotpoint
This commit is contained in:
Sagnik
@@ -0,0 +1,255 @@
|
||||
# Introduction for Sourik_ Biomimetic Agentic Orchestration Layer
|
||||
|
||||
**Date:** 2026-04-14
|
||||
**Status:** Team onboarding artifact
|
||||
**Primary Reader:** Sourik
|
||||
**Purpose:** Provide a single entry point into the biomimetic orchestration work so you can understand the intent, architecture, current implementation direction, and the exact document set without reconstructing the system from scattered files.
|
||||
|
||||
## 1. What This Project Is
|
||||
|
||||
This folder defines the next orchestration layer for Project Velocity.
|
||||
|
||||
The goal is not to build another chatbot and not to replace the current Python root. The goal is to build a governed colony-style agentic orchestration system that can sit on top of the current Project Velocity runtime and make Oracle, CRM, and later Catalyst operate through structured multi-agent missions instead of loose prompt chains.
|
||||
|
||||
The core design idea is biomimetic:
|
||||
|
||||
- the user-facing intelligence behaves like the queen interface
|
||||
- planning is handled by a decomposition layer
|
||||
- prompt specialization is handled by a prompt master layer
|
||||
- internal knowledge routing is handled by a librarian layer
|
||||
- external research is handled by a researcher layer
|
||||
- execution is handled by specialized workers
|
||||
- synthesis is handled by an aggregator
|
||||
- quality control is handled by a reviewer
|
||||
- governance remains outside worker prompts through a Nemoclaw-style guard plane
|
||||
|
||||
In practical engineering terms, this means:
|
||||
|
||||
- FastAPI root remains the authority for auth, persistence, domain ownership, and approvals
|
||||
- a TypeScript colony service becomes the orchestration kernel
|
||||
- Nemoclaw-derived policy remains the guard and writeback control plane
|
||||
- Oracle and CRM are the first real mission consumers
|
||||
|
||||
## 2. Why This Matters for Project Velocity
|
||||
|
||||
Project Velocity already has many of the right pieces:
|
||||
|
||||
- a real FastAPI backend
|
||||
- Oracle surfaces
|
||||
- CRM routes and state
|
||||
- Catalyst backend and UI
|
||||
- Sentinel sensing and analysis paths
|
||||
- MCP and Nemoclaw append layers
|
||||
|
||||
What it does not yet have is one disciplined orchestration spine that can:
|
||||
|
||||
- decompose work safely
|
||||
- distribute work by role
|
||||
- scope context instead of flooding every worker
|
||||
- preserve artifacts and evidence
|
||||
- review results before delivery
|
||||
- propose writebacks without bypassing root governance
|
||||
|
||||
This folder is the design and implementation program for that spine.
|
||||
|
||||
## 3. The Architectural Truth You Should Assume
|
||||
|
||||
If you work on this system, assume the following are already decided:
|
||||
|
||||
1. Python FastAPI root is the canonical product center.
|
||||
2. The colony service must integrate into the current root, not compete with it.
|
||||
3. Open Multi Agent concepts are being forked and reshaped, not adopted blindly.
|
||||
4. Nemoclaw concepts are being absorbed as governance and policy patterns, not as a second runtime center.
|
||||
5. Internal artifacts must be structured and persisted.
|
||||
6. Direct worker writeback is forbidden.
|
||||
7. Oracle advisory missions and CRM intelligence missions are the first practical targets because they are closest to real product value and sales readiness.
|
||||
|
||||
## 4. How to Read This Folder
|
||||
|
||||
Do not read this as a flat pile of documents. It has a deliberate reading order.
|
||||
|
||||
### 4.1 Start Here: Concept and Intent
|
||||
|
||||
Read these first:
|
||||
|
||||
- [Project Velocity - Biomimetic Agentic Orchestration Layer (First Principles).md](./Project%20Velocity%20-%20Biomimetic%20Agentic%20Orchestration%20Layer%20(First%20Principles).md)
|
||||
- [Product Requirements Document (PRD)_ Biomimetic Agentic Orchestration Layer.md](./Product%20Requirements%20Document%20(PRD)_%20Biomimetic%20Agentic%20Orchestration%20Layer.md)
|
||||
- [Software Requirements Specification (SRS)_ Biomimetic Agentic Orchestration Layer.md](./Software%20Requirements%20Specification%20(SRS)_%20Biomimetic%20Agentic%20Orchestration%20Layer.md)
|
||||
|
||||
These three define:
|
||||
|
||||
- why the system exists
|
||||
- what problem it solves
|
||||
- what the product and system boundaries are
|
||||
- what must be true for it to be technically legitimate
|
||||
|
||||
### 4.2 Then Read the Delivery and Build Plan
|
||||
|
||||
Read next:
|
||||
|
||||
- [Sprint 1 Plan_ Biomimetic Agentic Orchestration Layer.md](./Sprint%201%20Plan_%20Biomimetic%20Agentic%20Orchestration%20Layer.md)
|
||||
- [Implementation Blueprint_ Repository and Runtime Mapping.md](./Implementation%20Blueprint_%20Repository%20and%20Runtime%20Mapping.md)
|
||||
- [Execution Backlog_ Acceptance Ownership Sales Readiness.md](./Execution%20Backlog_%20Acceptance%20Ownership%20Sales%20Readiness.md)
|
||||
|
||||
These define:
|
||||
|
||||
- the build order
|
||||
- the runtime split
|
||||
- the exact repository direction
|
||||
- the acceptance gates
|
||||
- the path to something that is demo-safe and sellable
|
||||
|
||||
### 4.3 Then Read the Contract and Runtime Specs
|
||||
|
||||
Read next:
|
||||
|
||||
- [Mission Contracts and JSON Schemas Blueprint.md](./Mission%20Contracts%20and%20JSON%20Schemas%20Blueprint.md)
|
||||
- [Colony Database Schema and Root API Spec.md](./Colony%20Database%20Schema%20and%20Root%20API%20Spec.md)
|
||||
- [TypeScript Colony Service Internal Module Spec.md](./TypeScript%20Colony%20Service%20Internal%20Module%20Spec.md)
|
||||
|
||||
These define:
|
||||
|
||||
- what artifacts exist
|
||||
- how they are shaped
|
||||
- where they persist
|
||||
- what the root API looks like
|
||||
- how the TypeScript service should be structured internally
|
||||
|
||||
### 4.4 Then Read the Domain and Role Specs
|
||||
|
||||
Read next:
|
||||
|
||||
- [Oracle and CRM Adapter Detailed Implementation Spec.md](./Oracle%20and%20CRM%20Adapter%20Detailed%20Implementation%20Spec.md)
|
||||
- [Prompt Master, Librarian, and Researcher Role Spec.md](./Prompt%20Master,%20Librarian,%20and%20Researcher%20Role%20Spec.md)
|
||||
|
||||
These define:
|
||||
|
||||
- the first domain adapters that matter
|
||||
- the highest-leverage internal role boundaries
|
||||
- how execution quality is controlled before workers even start
|
||||
|
||||
### 4.5 Finally Read the Operating and Ticketing Layer
|
||||
|
||||
Read last:
|
||||
|
||||
- [Deployment, Operations, and Release Readiness Spec.md](./Deployment,%20Operations,%20and%20Release%20Readiness%20Spec.md)
|
||||
- [Implementation Ticket Breakdown and Dependency Matrix.md](./Implementation%20Ticket%20Breakdown%20and%20Dependency%20Matrix.md)
|
||||
|
||||
These define:
|
||||
|
||||
- how this becomes deployable
|
||||
- how it becomes safe to demo
|
||||
- how it becomes sliceable into tickets without architectural drift
|
||||
|
||||
## 5. The Most Important Project Decisions in This Folder
|
||||
|
||||
If you only retain a few truths from the full set, retain these:
|
||||
|
||||
### 5.1 Root Owns Truth
|
||||
|
||||
The colony service does not become the source of truth for domain state. Root FastAPI owns persistence, approvals, and domain write execution.
|
||||
|
||||
### 5.2 Colony Owns Orchestration
|
||||
|
||||
The TypeScript colony service owns:
|
||||
|
||||
- mission normalization
|
||||
- task graph planning
|
||||
- prompt packaging
|
||||
- worker execution
|
||||
- aggregation
|
||||
- review
|
||||
|
||||
### 5.3 Nemoclaw Owns Guard Semantics
|
||||
|
||||
Nemoclaw-style concepts are being used for:
|
||||
|
||||
- policy
|
||||
- tool scope
|
||||
- model routing
|
||||
- writeback control
|
||||
- auditability
|
||||
|
||||
### 5.4 Oracle and CRM Are the First Serious Use Cases
|
||||
|
||||
This is not an abstract framework exercise. The first meaningful mission classes are:
|
||||
|
||||
- Oracle advisory missions
|
||||
- CRM lead intelligence missions
|
||||
|
||||
Catalyst follows once those work reliably.
|
||||
|
||||
### 5.5 Artifacts Matter More Than Clever Prompts
|
||||
|
||||
The colony is being designed around explicit artifacts:
|
||||
|
||||
- mission envelope
|
||||
- task graph
|
||||
- prompt package
|
||||
- librarian pass
|
||||
- research artifact
|
||||
- worker result
|
||||
- aggregation packet
|
||||
- review packet
|
||||
- policy decision
|
||||
- writeback proposal
|
||||
|
||||
This is one of the main differences between a demo swarm and a productizable orchestration layer.
|
||||
|
||||
## 6. What You Should Pay Attention To First
|
||||
|
||||
Given your likely integration role, the highest-value docs for you are:
|
||||
|
||||
- [Implementation Blueprint_ Repository and Runtime Mapping.md](./Implementation%20Blueprint_%20Repository%20and%20Runtime%20Mapping.md)
|
||||
- [TypeScript Colony Service Internal Module Spec.md](./TypeScript%20Colony%20Service%20Internal%20Module%20Spec.md)
|
||||
- [Oracle and CRM Adapter Detailed Implementation Spec.md](./Oracle%20and%20CRM%20Adapter%20Detailed%20Implementation%20Spec.md)
|
||||
- [Colony Database Schema and Root API Spec.md](./Colony%20Database%20Schema%20and%20Root%20API%20Spec.md)
|
||||
- [Implementation Ticket Breakdown and Dependency Matrix.md](./Implementation%20Ticket%20Breakdown%20and%20Dependency%20Matrix.md)
|
||||
|
||||
These together answer the five questions that matter most for implementation:
|
||||
|
||||
1. Where does the system live in the repo?
|
||||
2. What does the TypeScript colony service need to look like?
|
||||
3. How does it connect to the Python root?
|
||||
4. What are the first domain missions?
|
||||
5. In what order should the team build this without creating chaos?
|
||||
|
||||
## 7. What This Folder Is Not
|
||||
|
||||
This folder is not:
|
||||
|
||||
- a code-complete implementation
|
||||
- a speculative research memo with no execution path
|
||||
- a replacement plan for Project Velocity root
|
||||
- a prompt-only system design
|
||||
|
||||
It is a build program. It is intended to be implementable by a real team under real product pressure.
|
||||
|
||||
## 8. Expected Outcome If We Build This Correctly
|
||||
|
||||
If this work is executed correctly, Project Velocity gets:
|
||||
|
||||
- a mission-oriented orchestration kernel
|
||||
- safer domain-aware multi-agent behavior
|
||||
- stronger Oracle and CRM intelligence flows
|
||||
- artifact-level auditability
|
||||
- a clearer path from internal automation to demo-safe commercial product behavior
|
||||
|
||||
That is the actual value of this project.
|
||||
|
||||
## 9. Suggested Next Step for You
|
||||
|
||||
The correct next move is:
|
||||
|
||||
1. read the five implementation-critical docs listed above
|
||||
2. challenge any unclear runtime boundary early
|
||||
3. convert the dependency matrix into actual implementation tickets
|
||||
4. start with contract layer, root schema, root gateway, and colony service bootstrap before adapter work
|
||||
|
||||
Do not start from UI polish or generic multi-agent experimentation. Start from the runtime spine.
|
||||
|
||||
## 10. Bottom Line
|
||||
|
||||
This folder is the design and implementation package for a biomimetic orchestration layer that absorbs the useful parts of Open Multi Agent and Nemoclaw into Project Velocity without breaking the current root architecture.
|
||||
|
||||
If you approach it in reading order, the logic is coherent. If you approach it as disconnected files, it will feel heavier than it really is. The intended outcome is a governed colony runtime that can make Project Velocity more operational, more defensible, and more sellable.
|
||||
Reference in New Issue
Block a user