# Initiative Brief: Operator Feature Parity in the Workspaces Orchestrator App ## Desired outcome The Orchestrator workspace app is the single place an operator does operator work. Everything reachable today only in the standalone control-plane UI — release planning and cutting, the operational dashboard, and the cross-initiative question queue — is available in the workspace app, consumed over the canonical `/orchestrator/*` API, authenticated as the real acting principal and scoped to an org and workspace. The standalone UI stays deployed. Its pages become a break-glass surface rather than the primary one, and it continues to host the control-plane API unchanged. ## Motivation Operator surfaces are split across two UIs with no rule about which gets new work, and the split is widening rather than closing. The release-management layer — the newest and largest operator capability built — landed entirely in the standalone UI, which was otherwise being treated as legacy. An operator now switches surfaces mid-task, and the workspace app cannot answer "what is being released?" at all. The cost is not only navigation. The standalone UI attributes every action to a single static operator identity and is reachable by anyone who can reach the host; the workspace app authenticates a real principal and scopes to an org and workspace. Work that matters — publishing a GitHub release, answering a blocking question — is better done where the record says who did it. ## Current state - The workspace app (`Xyence/workspaces`, `apps/orchestrator`) has: home, initiatives list and detail, brief revision, work-item detail, initiatives/new, workers list and worker detail. - The standalone UI (`Xyence/orchestrator`, `apps/web`) has: home, initiatives detail, initiatives/new, **`/ops`**, **`/questions`**, **`/release-plans`**, **`/release-plans/[id]`**, **`/releases`**, **`/releases/[id]`**. - Only the standalone UI has releases, ops and a cross-initiative question queue. Only the workspace app has worker pages and work-item detail. - `apps/web` is also the control plane: it serves 125 `/api/*` routes (worker claim, heartbeat, progress, GitHub webhooks, admin/ops JSON) and 21 `/orchestrator/*` routes. It cannot be removed; only its pages are candidates for removal. - The canonical `/orchestrator/*` surface today covers initiatives, waves, work items, questions **within one initiative**, release *readiness* for one initiative, and workers. It exposes **nothing** for release plans, release publishing, or the operational dashboard. - The standalone pages are server components that read the database directly (`getDatabase()`, `buildOperationalDashboard`, `listQuestions`). The workspace app is in a different repository behind an HTTP boundary and cannot do this; every surface it gains needs a canonical endpoint. - Approximate sizes: release UI ~1,220 lines across 7 components plus ~240 lines of pages; ops ~426 lines plus a 30-line page; questions ~112 lines plus a 232-line card component. - `/api/admin/ops/dashboard` already serves the same aggregation the ops page renders, so the ops surface is closer to a re-host than a rebuild. - Release mutations are the only genuinely new authorization surface: create, add initiatives, set repositories, prepare, edit notes, publish, retry, cancel, and target ordering — roughly fourteen endpoints, today answering as the static operator actor. ## Product principles - One operator UI for everyday work; the operator should never have to know which app owns a task. - No capability regresses during the migration. A surface appears in the workspace app before anyone is asked to stop using its counterpart. - Break-glass access survives. An operator must retain a way to act when platform auth or the Console gateway is unavailable. - Read-only surfaces can move quickly; anything that mutates production waits for real principal attribution. ## Architectural principles - The workspace app consumes `/orchestrator/*` over HTTP and never reaches the orchestrator database directly. - The controller adapts to the canonical contract, not the client. Vocabulary translation, status mapping and shape changes belong on the controller side, as established when the worker surface was made canonical. - New canonical endpoints are principal-scoped: the acting operator is derived from the platform session, not a static actor. - The canonical surface publishes an empty result distinctly from an absent one, so "nothing to show" and "not implemented" never look the same to a client. - No new credential surfaces. The workspace app reuses its existing authenticated, scoped API client. ## Domain concepts - **Workspace app**: `Xyence/workspaces`, `apps/orchestrator`; the Orchestrator workspace served at `orchestrator.workspaces.xyence.io`, authenticated and org/workspace scoped. - **Standalone control-plane UI**: `Xyence/orchestrator`, `apps/web` pages; the admin surface at `orchestrator.xyence.io`, attributed to a static operator actor. - **Canonical surface**: the `/orchestrator/*` API the workspace app is written against; the stable contract for automation and MCP intake as well as this frontend. - **Break-glass**: operating the platform when platform auth or the Console gateway is down. - **Release plan**: the publish lifecycle object (`/api/release-plans/*`); distinct from **release targets** (`/api/releases/*`), which drive deploys. ## Decisions - The standalone UI stays deployed for now; this initiative does not remove it. — Operator decision, 2026-08-14. - The workspace app is the operator UI going forward; new operator surfaces belong there. — Follows from the split this initiative exists to close. - `apps/web` remains the control-plane API host regardless of what happens to its pages. — It serves the worker endpoints, webhooks and the canonical surface itself. - Release *services* stay in `Xyence/orchestrator`. Only the operator interface moves. — The service owns the database and the GitHub integration. ## Rejected / deferred alternatives - Delete `apps/web` once the pages move. Rejected — it is the control plane, not just a UI. - Delete the standalone pages as each surface lands. Deferred, not rejected — break-glass has real value while the Console gateway is still proxying incompletely. Revisit when parity is complete and the gateway is sound. - Have the workspace app read the orchestrator database directly. Rejected — it is a separate repository and deployment; the HTTP contract is the boundary. - Move the release service code into Workspaces. Rejected — it owns the schema, the audit trail and the GitHub release integration. - Publish `@xyence/` packages to consume the shell from `Xyence/orchestrator`. Rejected for this initiative — the surfaces move toward the workspace app, not the reverse. ## Constraints - Two repositories change: `Xyence/workspaces` (the app and its API client) and `Xyence/orchestrator` (new canonical routes only — no page changes). - `.github/workflows/**` is a protected path in both repositories. - No new credentials, tokens or auth schemes; reuse the existing scoped client and platform session. - Existing standalone URLs keep working while the standalone UI remains deployed. - Release publishing acts on real GitHub releases; behaviour must not change as a side effect of exposing it canonically. ## Invariants - A publish, retry or cancel performed from the workspace app records the real acting principal, never a static operator actor. - Backend authorization stays authoritative: the workspace app renders what it is allowed to see, and never decides access itself. - Partial-failure semantics of release publishing are preserved exactly — per-repository outcomes, `retryable` classification, and retry that skips what already published. - No workspace-scoped surface leaks data across orgs or workspaces. - Nothing in this initiative alters the worker protocol, the review gate, or deploy behaviour. ## Repository scope - `Xyence/workspaces` — `apps/orchestrator` (pages, components, nav), `packages/api-client`. - `Xyence/orchestrator` — `apps/web/src/app/orchestrator/**` (new canonical routes), `apps/web/src/server/**` (projections). No changes to `apps/web` pages. ## Expected behavior - An operator opens the Orchestrator workspace and sees release plans: their state, participating repositories, pinned commits, notes and per-repository publish outcomes. - Preparing, editing notes, publishing, retrying a failed publish and cancelling are all possible from the workspace app, with the acting operator recorded. - An operational dashboard shows component health, worker presence, current executions and active incidents, matching what the standalone `/ops` page shows today. - A single queue lists every open question across initiatives, and answering from it behaves exactly as answering from within an initiative does. - The standalone UI continues to work unchanged throughout. ## Open questions - Should release mutations require an admin role, or is any workspace member with access sufficient? The canonical auth layer already distinguishes admin from viewer. - Should the operational dashboard be visible to any member, or restricted to admins? It exposes worker identities, incidents and execution state. - Is the cross-initiative question queue a workspace-scoped view, or genuinely global? Questions belong to initiatives, which belong to workspaces. - How long does break-glass remain? Naming a condition for retiring the standalone pages — rather than a date — would keep the decision honest.