# Agent Platform Gaps - Roadmap Index

> **Purpose:** Turn the current agent-company platform gaps into an actionable roadmap set.
>
> **Scope:** `learning_ai_common_plat`
>
> **Date:** 2026-03-14
>
> **Status:** Planned

---

## Executive Summary

The shared platform already covers a large amount of generic SaaS infrastructure:
auth, telemetry, diagnostics, flags, delivery, jobs, marketplace, billing-related
modules, extraction, MCP tooling, and durable queue primitives.

What is still missing is the **agent control plane**:

1. durable agent run orchestration
2. org/workspace/team/RBAC
3. agent registry and prompt versioning
4. reusable knowledge/RAG
5. human review and approval queue
6. support case management
7. durable cross-service eventing and worker runtime
8. centralized AI governance and evals
9. AI budget and cost governance
10. enterprise provisioning and SCIM

This roadmap set breaks those gaps into separate implementation documents so they
can be sequenced without mixing concerns.

---

## Default Platform Decisions

To make the roadmap executable, these should be treated as the default assumptions
unless a later ADR explicitly changes them:

- **Control plane remains in `platform-service`.**
- **`mcp-server` remains an execution and tooling surface, not the system of record.**
- **`@bytelyst/queue` remains the immediate job primitive.**
- **Redis is the first new infrastructure dependency to add** for durable eventing,
  coordination, leases, and future worker scale-out.
- **Do not introduce Temporal in v1.** Design for Temporal compatibility, but do not
  pay the operational cost before the platform proves it needs workflow-native semantics.
- **Do not force all new domains into Cosmos.** Relational domains should be allowed to
  move to PostgreSQL when they become awkward or risky in document storage.
- **Human review, governance, and budget controls are mandatory platform capabilities,**
  not optional product features.

---

## Roadmap Set

1. [Agent Runtime & Orchestration Roadmap](./platform_AGENT_RUNTIME_ORCHESTRATION_ROADMAP.md)
2. [Org, Workspace & RBAC Roadmap](./platform_ORG_WORKSPACE_RBAC_ROADMAP.md)
3. [Agent Registry & Prompt Versioning Roadmap](./platform_AGENT_REGISTRY_PROMPT_VERSIONING_ROADMAP.md)
4. [Knowledge & RAG Service Roadmap](./platform_KNOWLEDGE_RAG_SERVICE_ROADMAP.md)
5. [Human Review & Approval Queue Roadmap](./platform_HUMAN_REVIEW_APPROVAL_QUEUE_ROADMAP.md)
6. [Support Case Management Roadmap](./platform_SUPPORT_CASE_MANAGEMENT_ROADMAP.md)
7. [Durable Event Bus & Worker Runtime Roadmap](./platform_DURABLE_EVENT_BUS_AND_WORKER_RUNTIME_ROADMAP.md)
8. [AI Governance & Evaluation Roadmap](./platform_AI_GOVERNANCE_EVALS_ROADMAP.md)
9. [AI Budget & Cost Governance Roadmap](./platform_AI_BUDGET_COST_GOVERNANCE_ROADMAP.md)
10. [Enterprise Provisioning & SCIM Roadmap](./platform_ENTERPRISE_PROVISIONING_SCIM_ROADMAP.md)

---

## Reuse Map

These roadmaps are **not** intended as ten pure greenfield systems. The repo already
contains partial foundations that should be extended wherever possible.

| Roadmap                            | Existing Components To Reuse Or Extend                                                                                                                      | New Work vs Extension                                                              |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Agent Runtime & Orchestration      | `packages/queue`, `services/platform-service/src/modules/jobs`, `services/mcp-server/src/modules/a2a`                                                       | Mostly extension with one new system-of-record module                              |
| Org, Workspace & RBAC              | `services/platform-service/src/modules/auth`, `services/platform-service/src/modules/auth/enterprise`, current membership model in auth types               | New tenant model built on existing auth                                            |
| Agent Registry & Prompt Versioning | `services/mcp-server/src/modules/tools`, A2A pipelines, existing blob/storage packages                                                                      | New registry layer, but runtime integration should reuse current MCP/A2A assets    |
| Knowledge & RAG Service            | `services/extraction-service`, `services/platform-service/src/modules/ai-diagnostics`, `packages/extraction`, storage/blob packages                         | Mostly extension plus a new shared retrieval module                                |
| Human Review & Approval Queue      | `services/platform-service/src/modules/auth/push-approvals`, `services/platform-service/src/modules/delivery`, `packages/queue`                             | New generalized review domain built from existing approval and delivery primitives |
| Support Case Management            | `services/platform-service/src/modules/diagnostics`, `services/platform-service/src/modules/audit`, `services/mcp-server/src/modules/support/debug-pack.ts` | New case domain with heavy reuse of diagnostics context                            |
| Durable Event Bus & Worker Runtime | `packages/events`, `packages/queue`, existing background job patterns in `platform-service`                                                                 | Direct extension, not greenfield                                                   |
| AI Governance & Evaluation         | `services/extraction-service/evals`, `services/platform-service/src/modules/ai-diagnostics`, flags/experiments infrastructure                               | New governance surface built on existing eval/diagnostic pieces                    |
| AI Budget & Cost Governance        | `services/platform-service/src/modules/usage`, `plans`, `subscriptions`, `licenses`, `telemetry`                                                            | Extension of existing usage/billing controls with AI-specific attribution          |
| Enterprise Provisioning & SCIM     | `services/platform-service/src/modules/auth/enterprise`, current auth and membership structures, queue/runtime primitives for reconciliation                | Extension of enterprise auth, not a separate identity platform                     |

---

## What Is Truly Net-New

Only a few parts are genuinely net-new platform domains:

- canonical org/workspace/team model
- agent registry and prompt versioning as a data system
- generalized human review queue
- support case records

Everything else should start by extending current packages or modules.

---

## Existing Repo Signals

These gaps are not theoretical. The current codebase already shows the partial
foundations and the missing layers:

- Durable queue primitives now exist in `packages/queue/`, but agent orchestration in
  `services/mcp-server/src/modules/a2a/runner.ts` is still primarily log-driven.
- `platform-service` has broad product infrastructure, but there is no first-class
  org/workspace/team module under `services/platform-service/src/modules/`.
- Enterprise IdP support exists in `services/platform-service/src/modules/auth/enterprise/`,
  but enterprise provisioning does not.
- The event bus in `packages/events/src/memory.ts` is in-process only.
- `ai-diagnostics` already uses embeddings and vector similarity, but there is no reusable
  knowledge service for general agent retrieval.
- MFA push approvals exist, but there is no general review queue for agent actions.

---

## Recommended Build Order

### P0

1. Agent Runtime & Orchestration
2. Durable Event Bus & Worker Runtime
3. Org, Workspace & RBAC
4. Human Review & Approval Queue

### P1

5. Agent Registry & Prompt Versioning
6. Knowledge & RAG Service
7. AI Budget & Cost Governance
8. AI Governance & Evaluation

### P2

9. Enterprise Provisioning & SCIM
10. Support Case Management

---

## Dependency Graph

The ten roadmaps are not independent. The strongest sequencing is:

1. **Durable Event Bus & Worker Runtime**
   This provides the durable execution substrate for the rest.
2. **Agent Runtime & Orchestration**
   Depends on durable workers and queue conventions.
3. **Org, Workspace & RBAC**
   Required before tenant-safe approval, retrieval, and enterprise provisioning.
4. **Human Review & Approval Queue**
   Depends on agent runs and tenant boundaries.
5. **Agent Registry & Prompt Versioning**
   Depends on agent runs for production traceability and on governance for release gates.
6. **AI Governance & Evaluation**
   Depends on registry/versioning to attach decisions to concrete artifacts.
7. **AI Budget & Cost Governance**
   Depends on tenant model and run/request attribution.
8. **Knowledge & RAG Service**
   Depends on tenant boundaries for safe retrieval.
9. **Enterprise Provisioning & SCIM**
   Depends on org/workspace/team model.
10. **Support Case Management**
    Depends on runs, reviews, tenanting, and diagnostics links to be genuinely useful.

---

## Success Criteria For The Roadmap Set

This roadmap family should be considered successful only when it produces:

- a clear execution order rather than ten disconnected ideas
- a default architecture stance for this repo
- explicit separation between **best industry-standard stack** and **best immediate fit**
- enough detail to derive implementation epics without rewriting the docs from scratch

---

## Architectural Guidance

These docs assume the current repo direction remains:

- TypeScript + Fastify services
- shared `@bytelyst/*` packages
- `platform-service` as control plane
- `mcp-server` as operator and A2A interface

However, some missing capabilities are more naturally relational or workflow-heavy
than the current Cosmos-first platform modules. Each roadmap therefore includes:

- a **recommended stack** for long-term quality
- a **repo-fit alternative** that stays closer to current conventions
- a **default decision for this repo now**
- explicit **dependencies** and **v1 non-goals**

That is intentional. The best industry-standard choice is not always the same as
the least disruptive repo-local choice.
