Project_Velocity/.Agent Context/Sprint 1/Biomimetic Agentic Orchestration Layer/Introduction for Sourik.md

# 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.