# Initiative Brief: Complete conversational shell integration in the Orchestrator workspace ## Desired outcome Make the Orchestrator workspace consume the platform-owned conversational shell capabilities that already exist in `@xyence/shell`, so an authenticated Orchestrator user sees and can use the real conversation history and Composer alongside the Orchestrator domain UI instead of the current placeholder regions. The delivered experience should reuse the existing shared conversation, Composer, attachment, screenshot, persistence, runtime, confirmation, audit-receipt, and context infrastructure rather than creating an Orchestrator-specific chat implementation. This initiative is specifically about closing the Orchestrator integration gap. It must **not** be interpreted as an instruction to rewrite Orchestrator onto canonical Sales routing or otherwise reshape the application solely to match the Sales module topology. ## Motivation The “Workspace Shell, Context Contract, and Conversational Runtime” initiative successfully delivered the shared platform capabilities, but the Orchestrator workspace was only integrated with the first shell-layout stage. Its current app-local `PlatformShell` still contains the placeholder conversation and Composer regions introduced before the conversational runtime landed. As a result, production presents an internally inconsistent shell: - the global header and org/workspace switcher are present; - contract-driven navigation is present; - Orchestrator domain UI is present; - the platform conversational surface is absent even though its shared implementation has been delivered. This is an integration gap, not a missing feature implementation and not an environment/feature-flag problem. ## Current state - `apps/orchestrator` runs inside an app-local `PlatformShell`. - That shell renders contract-driven navigation and primary Orchestrator UI. - Its conversation-history and Composer regions remain static placeholders. - `@xyence/shell` already contains the platform Composer and conversation infrastructure. - Shared conversation capabilities include durable history, context events, attachments/screenshots, runtime send/retry, confirmation UX, and audit receipts. - `WorkspaceContainer` supplies workspace-scoped context management for canonical module-hosted workspaces. - Sales is currently the concrete workspace that mounts the shared conversation surface. - Orchestrator uses a different topology: a standalone Next application with root-level routes, its own `OrchestratorShell`, and its existing authenticated/scoped API client. - Orchestrator’s provider tree currently provides authentication, API client, telemetry, and org/workspace scope, but not the full conversation provider/runtime/upload wiring. - No current open Workspaces issue explicitly owns completion of the Orchestrator conversational-shell integration. ## Product principles - Conversation is a platform capability, not an Orchestrator-specific feature. - The conversational surface should be consistently available alongside focused domain UI. - Existing Orchestrator navigation and operational screens must remain first-class; conversation augments them rather than replacing them. - A user should not need to understand whether a workspace happens to be hosted through `WorkspaceContainer` or a standalone Next application. - Workspace switching must switch conversational scope without leaking history between workspace instances. - Navigation within the same workspace should refine conversational context rather than implicitly create a new conversation. ## Architectural principles - Reuse `@xyence/shell` conversation and Composer components; do not fork their behavior into `apps/orchestrator`. - Reuse `@xyence/api-client` conversation/runtime/upload clients and the existing authenticated/scoped Orchestrator API client wherever their contracts permit. - Preserve the Orchestrator application’s current backend authorization boundary. - Do not put control-plane credentials, service JWTs, provider credentials, or other secrets in the browser. - The active organization/workspace selected by the existing `OrgWorkspaceProvider` remains the authoritative browser-side scope input. - The implementation should identify the correct reusable shell composition boundary instead of blindly forcing the Orchestrator app through `WorkspaceContainer` if that would duplicate routing or authorization responsibilities. - Shell-owned regions remain platform-owned; Orchestrator contributes semantic context and domain UI, not custom conversational JSX or a parallel chat implementation. - **Do not interpret this initiative as “rewrite Orchestrator onto canonical Sales routing.”** Sales is a useful reference consumer of the shared shell, not the required application architecture for Orchestrator. Preserve Orchestrator’s existing route topology unless discovery proves a specific change is necessary to provide the shared conversational shell cleanly. ## Domain concepts - **Conversational shell surface**: the platform-owned conversation history, Composer, send state, confirmations, attachments, and receipts displayed alongside workspace domain UI. - **Workspace conversation scope**: the active `workspaceId` under which conversations are listed, created, resumed, and persisted. - **Semantic context**: the currently relevant Orchestrator domain object or view published into the conversation without changing workspace identity. - **Orchestrator shell adapter**: the minimum app-specific composition required to connect Orchestrator’s existing Next/auth/scope topology to the shared shell conversation capabilities. - **Primary domain surface**: the existing Orchestrator initiatives, workers, work items, planning, recovery, release-readiness, and related UI. ## Decisions - The shared `@xyence/shell` implementation is the canonical home of Composer and conversation UI. - Conversation persistence and runtime operations use platform backend APIs and authenticated browser session plumbing. - Conversation history is workspace-scoped. - Navigation does not implicitly create a conversation. - Mutating conversational capabilities require deterministic confirmation and durable receipts. - Attachments and screenshots remain user-initiated and retain contextual provenance. - Existing Orchestrator control-plane credentials remain server-side. - Existing Orchestrator domain screens and route structure should not be rewritten merely to obtain the Composer. - Sales’ canonical `/w/:workspaceId/*` module topology is not a prerequisite for Orchestrator conversational-shell integration. ## Rejected / deferred alternatives - Build a second Orchestrator-specific Composer or chat panel — rejected. This would immediately fork platform behavior. - Gate the existing Composer behind a new Orchestrator-only environment flag — rejected unless discovery proves a genuine deployment requirement. The missing surface is currently an integration gap, not a feature-toggle decision. - Rewrite Orchestrator onto canonical Sales routing or force it through the Sales-style module topology solely to obtain the Composer — rejected. Reuse the platform capabilities without unnecessary routing or application-topology churn. - Move the entire Orchestrator application to canonical `/w/:workspaceId/` routing as part of this initiative — deferred unless required by a demonstrated architectural constraint independently worth making. This initiative should close the conversational-shell gap without using it as a pretext for a routing migration. - Expose controller service credentials to the browser so conversation tools can call the controller directly — rejected. - Reimplement conversation persistence or runtime in the Orchestrator backend/controller — rejected; consume the existing platform facilities. - Add Orchestrator-specific conversational tools as part of this initiative — deferred. First make the platform conversation surface correctly available and operational. ## Constraints - Primary repository is `Xyence/workspaces`. - Supporting backend changes should occur only if discovery finds an actual missing API contract in `Xyence/outshine` or the Console gateway. - Existing Orchestrator authenticated domain reads/writes and service-side controller adapters must continue to work unchanged. - Existing org/workspace switcher behavior must remain functional. - Existing Orchestrator route topology should remain intact unless a narrowly justified change is required for the integration. - Cross-workspace conversation leakage is unacceptable. - The implementation must work under the canonical cookie/CSRF session boundary. - Existing shared conversation components and clients should be extended only where a genuinely reusable seam is missing. - Do not make production/deployment changes merely to compensate for missing application wiring. - Responsive behavior and accessibility of the shared Composer/timeline must be preserved. ## Invariants - Backend authorization remains authoritative. - Active workspace scope accompanies every relevant conversation request. - Conversation history from workspace A is never shown after switching to workspace B. - A route change inside the same selected workspace does not automatically create a new conversation. - The Composer never holds platform/provider/control-plane secrets. - Mutating conversational actions cannot bypass the existing deterministic confirmation contract. - Orchestrator-owned primary UI never injects arbitrary JSX into shell-owned conversation regions. - Existing Orchestrator operational behavior remains usable if the conversation backend is unavailable; conversational failure should degrade visibly rather than blank or break the domain workspace. - The shared shell remains the canonical implementation of Composer/timeline behavior. - Orchestrator does not need to adopt Sales routing semantics in order to satisfy this initiative. ## Repository scope - `Xyence/workspaces` — primary implementation: Orchestrator shell/provider integration, semantic-context publication, styling/layout reuse, tests, and removal of obsolete placeholder regions. - `Xyence/outshine` — only if a discovered conversation API/runtime capability is actually missing for an Orchestrator workspace scope. - `Xyence/console` — only if the existing Workspaces BFF proxy does not currently forward a required conversation/runtime/upload route. - `Xyence/orchestrator` — no feature implementation expected unless discovery identifies a missing authoritative Orchestrator capability that the shared runtime must call; ordinary Composer integration belongs in Workspaces. ## Expected behavior - An authenticated user entering the Orchestrator workspace sees the real platform conversation history and Composer rather than placeholder copy. - The conversation surface uses the currently selected organization/workspace from the existing Orchestrator switcher. - Switching workspaces loads that workspace’s conversation history or its appropriate empty/start state and never retains the prior workspace’s messages. - The user can create or resume a conversation, type and send a message, and see the persisted user and assistant turns after reload. - Runtime send failures produce the existing safe error/retry experience rather than breaking the Orchestrator domain UI. - The user can attach files and initiate screenshots through the existing shared Composer behavior where browser support permits. - Attachment and screenshot messages retain the active Orchestrator page/domain context supported by the shared context contract. - The Orchestrator workspace publishes useful semantic context for at least the principal object-detail routes where stable identifiers already exist, such as initiative and work-item detail, without inventing new authorization semantics. - Navigating between Orchestrator views updates/refines semantic context while retaining the active conversation. - Mutating actions requested through conversation retain the shared explicit-confirmation and audit-receipt UX. - Existing Orchestrator navigation, initiative/work-item/worker screens, workspace switcher, user menu, route telemetry, and permission-denied behavior continue to work. - Existing Orchestrator URLs continue to work; this initiative does not require users to move to Sales-style `/w/:workspaceId/*` routes. - At desktop widths the domain UI and conversational surface are simultaneously usable; at narrow widths the shared responsive behavior remains usable without inaccessible controls or clipped content. - No “Composer coming soon” or “Conversation history will appear here” placeholder remains in the production Orchestrator shell. ## Open questions - What is the cleanest reusable composition for standalone workspace apps like Orchestrator: enhance the shared platform shell to own `ConnectedConversationPanel`, introduce a reusable shell-conversation adapter/provider, or compose the existing primitives directly in `OrchestratorShell`? - Which shared provider/client construction currently exists only implicitly in the Sales/canonical-container path and should be extracted so standalone apps can consume it without duplication? - Does the Console `/api/workspaces/*` proxy already forward all conversation, runtime, confirmation, and upload paths required by the Orchestrator app? - Which Orchestrator routes have stable domain identities worth publishing as semantic context in this pass? - Should conversation UI appear for actors who can enter the workspace but lack some Orchestrator-specific capability, with the backend independently authorizing conversation tools as today? - What graceful state should be shown if conversation APIs are unavailable while the Orchestrator control-plane UI itself remains healthy? - Can the integration be completed while preserving the existing Orchestrator root-level Next route topology? This should be the default assumption; a routing migration requires separate architectural justification and must not be inferred from Sales being the current reference implementation.