Skip to main content

Workspace Composition Platform v0 Roadmap

This roadmap turns the workspace composition architecture into an executable project. The non-negotiable invariant is:

Host resolves runtime.
Composer composes structure.
Render runtime executes UI.
ClaudeWorkspace packages product defaults.
Modules are trusted React UI adapters, not state/runtime owners.

Phase 0: Decision Freeze And Specs​

Goal: freeze the API direction before package work begins.

Deliverables:

  • canonical decision register
  • module authoring spec v0
  • namespace, diagnostics, and versioning spec
  • security and trust model v0
  • composition kernel spec v0
  • render runtime spec v0
  • migration map from current Claude UI surfaces to contribution descriptors

Acceptance standards:

  • every spec links to decision IDs
  • every future issue can cite at least one locked decision
  • all v0 non-goals are explicitly listed
  • no spec requires React inside @maya/assistant-composition
  • no spec requires modules to own persistent state

Risks:

  • over-specifying future sandbox or marketplace behavior
  • leaving render handle taxonomy too vague for implementation
  • hiding security limits behind permission-like language

Non-goals:

  • implementation code
  • package publishing
  • route replacement as a public API
  • default text message override

Phase 1: Headless Composition Kernel​

Goal: create the pure composition layer and prove it with fixtures.

Deliverables:

  • @maya/assistant-composition package skeleton
  • core headless types
  • schema version fields
  • module instance namespace utilities
  • v0 contribution descriptors
  • v0 composition policy shape
  • structured diagnostics
  • composeWorkspace() returning result object
  • golden composition fixture tests

Acceptance standards:

  • package has no React, DOM, CSS, fetch, storage, or localStorage dependency
  • duplicate instance IDs fail with diagnostics
  • route path conflicts fail unless policy resolves them
  • renderer claim conflicts fail unless policy resolves them
  • built-ins and modules enter the same pipeline
  • fixtures cover ready, read-only, disabled, needs-configuration, unauthorized, and error module states

Risks:

  • CompositionPolicy becoming a rule language
  • fallback surfaces becoming runtime decision logic
  • contribution descriptors becoming product-specific too early

Non-goals:

  • React rendering
  • host runtime resolution
  • backend policy checks
  • marketplace metadata
  • remote module loading

Phase 2: Claude Built-Ins As Contributions​

Goal: model existing Claude workspace surfaces as first-class contributions without visual change.

Deliverables:

  • @maya/claude-workspace package boundary plan
  • Claude built-in descriptors for routes, sidebar, settings, customize, transcript, tools, activities, and fallbacks
  • migration table from current hard-coded surfaces to descriptors
  • default composition policy for Claude product kit
  • compatibility harness proving current product shell can still render

Acceptance standards:

  • current workspace visuals and navigation remain unchanged
  • built-ins are not special-cased outside the composer
  • product-specific defaults live outside @maya/assistant-composition
  • route, sidebar, and surface ownership can be inspected in diagnostics

Risks:

  • moving React pages before descriptors are stable
  • leaking Claude-specific controller assumptions into composition types
  • creating two parallel route pipelines

Non-goals:

  • public built-in replacement API
  • arbitrary panel slots inside built-in pages
  • final package publishing

Phase 3: Scoped React Render Runtime​

Goal: introduce explicit executable UI resolution without global registration.

Deliverables:

  • ReactRenderRuntime interface
  • ReactRenderPack format
  • handle coverage validation
  • unknown handle fallback
  • ErrorBoundary policy
  • preload policy for route, visible, intent, and never
  • core eager render strategy for shell and default transcript
  • diagnostics bridge from runtime to UI

Acceptance standards:

  • render handles never contain components or dynamic imports
  • host passes render runtime explicitly
  • missing handle reports a structured diagnostic
  • core shell/default chat can render eagerly
  • module pages and custom renderers can lazy load
  • multiple workspace instances can use different render runtimes in one process

Risks:

  • render runtime becoming an implicit module loader
  • lazy boundaries creating poor UX for core surfaces
  • trust policy being mistaken for sandboxing

Non-goals:

  • remote ESM
  • module federation
  • iframe execution
  • automatic render pack discovery
  • React Server Components support

Phase 4: Composition-Based Workspace Rendering​

Goal: make AssistantWorkspace render a WorkspaceComposition through a scoped render runtime.

Deliverables:

  • AssistantWorkspace composition input
  • createClaudeWorkspaceRuntime() deterministic builder
  • removal of hard-coded route switching from the primary path
  • diagnostics surface for development and fallback states
  • Storybook scenarios for composed routes, conflicts, and missing handles

Acceptance standards:

  • createClaudeWorkspaceRuntime(...) plus explicit AssistantWorkspace composition/render-runtime wiring produces one deterministic composition and scoped render runtime
  • no hidden global state is introduced
  • host controllers remain host-owned
  • existing app smoke tests still pass
  • diagnostics can be shown without crashing the workspace

Risks:

  • breaking current web app integration
  • controller props becoming a product-specific backdoor
  • route context freezing too early

Non-goals:

  • deleting legacy paths before parity
  • complete settings/customize refactor
  • public route replacement API

Phase 5: Developer Module Happy Path​

Goal: prove a developer can install, import, resolve, compose, and render a trusted module.

Deliverables:

  • first-party sample module
  • module package authoring guide
  • 10-minute happy path
  • conformance checklist
  • module CSS scope checks
  • multi-instance example
  • custom route, sidebar item, configuration surface, integration card, custom tool renderer, and fallback surface

Acceptance standards:

  • sample module can be enabled twice with different instanceId values
  • module has no persistent state owner API
  • module CSS is scoped under .aui-root
  • module render pack is explicitly passed by host
  • missing render pack produces actionable diagnostics
  • docs show the current createClaudeWorkspaceRuntime(...) plus AssistantWorkspace path, and may include clearly labeled non-runnable target sketches for future ClaudeWorkspace/ClaudeWorkspaceRenderer facades

Risks:

  • sample becoming too complex
  • authoring guide exposing too many internal types
  • CSS rules relying on trust instead of testable conventions

Non-goals:

  • marketplace
  • online install
  • untrusted module sandbox
  • cross-module dependency graph
  • module-owned storage adapters

Phase 6: Release Gates And Documentation​

Goal: make v0 releasable without relying on tribal knowledge.

Deliverables:

  • workspace package classification registry
  • package boundary verifier updates
  • docs structure verifier updates
  • composition contract test command
  • render runtime smoke command
  • consumer smoke app for product kit
  • release notes template
  • open decision log

Acceptance standards:

  • CI covers new packages
  • release gate fails if headless package imports React, DOM, CSS, fetch, or storage
  • public API snapshots include new packages
  • docs link decisions, roadmap, and issue backlog
  • consumer smoke proves the happy path outside source paths

Risks:

  • CI cost growth
  • package version drift
  • duplicate documentation truth

Non-goals:

  • final semver automation for all future packages
  • visual matrix for every third-party module
  • marketplace trust checks

Milestone Exit Order​

Phase 0 exits before any public API is treated as stable.

Phase 1 exits before render runtime implementation starts.

Phase 2 exits before hard-coded Claude routes are removed from the primary rendering path.

Phase 3 exits before module sample packages are treated as supported.

Phase 4 exits before developer-facing docs claim the composition path is the default.

Phase 5 exits before package release candidates.

Phase 6 exits before v0 publication.