Ultra Creative Studio OpenCode Fork Roadmap

Status: Strategy & Architecture Roadmap (UC-Studio Feedback Incorporated)

Date: 2026-08-10

Scope: The rustybret/opencode fork as the primary Ultra Creative Studio (UCS) frontend and runtime. This document does not plan implementation work for the Codex, Claude, or Pi/Senpi hosts except where their shared contracts constrain the OpenCode design.

Executive Decision

Make the OpenCode fork the UCS reference application: the place where UCS owns the user experience for desktop, Web, TUI, CLI, and server operation. Keep the UCS/OmO capability layer portable so the same agent, skill, tool, and integration concepts can continue to serve Codex, Claude, and Pi/Senpi through their adapters.

The target architecture is deliberately split into three planes:

Upstream OpenCode plane: provider/runtime/session/server primitives kept as close to upstream/dev as practical.
UCS capability plane: harness-neutral agents, skills, tools, project/work coordination, SuperMCP contracts, memory, and policy.
UCS OpenCode frontend plane: fork-owned Web, Desktop, TUI, CLI, server/API presentation, navigation, workflows, and opinionated defaults.

The fork should diverge intentionally in the frontend plane, not accidentally throughout the runtime. The plugin remains the compatibility and capability seam; the fork becomes the product surface.

Evidence Base

This draft is grounded in:

The fork's two-branch maintenance model and script/fork-sync.sh.
OpenCode package boundaries under packages/app, packages/desktop, packages/tui, packages/opencode, packages/plugin, packages/protocol, packages/schema, and generated SDKs.
The current OpenCode plugin contract in packages/plugin/src/index.ts.
The OpenCode V2 Effect and Promise plugin API design under packages/plugin/src/v2/.
UCS repository documentation in /Volumes/Topper2TB/Git/uc-studio/README.md and AGENTS.md.
The UCS OpenCode adapter contract in uc-studio/packages/omo-opencode/.
Structured feedback received from uc-studio-8ce41322 on 2026-08-10 (mailbox message ID 134fb143-3462-4234-b928-93b1d53806fe; trace recorded in .omo/mailbox-trace.jsonl).
Primary upstream documentation and source references listed in Research Sources.

Feedback status

The direct uc-studio project is registered in the repository-local allowlist as uc-studio-8ce41322, and the plan-tier feedback request has been answered: structured feedback arrived on 2026-08-10 as mailbox message 134fb143-3462-4234-b928-93b1d53806fe (trace in .omo/mailbox-trace.jsonl) and is treated as UCS-agent input to this revision. Phase 0 is no longer blocked on missing feedback; the remaining Phase 0 blocker is the dual context-ownership conflict between packages/core/src/system-context/index.ts and packages/core/src/session/context-epoch.ts, which must be resolved (Option 1 preferred) before any write path is implemented.

Product Thesis

UCS should not be an OpenCode skin or a collection of prompts. It should be an opinionated creative-production environment in which:

humans, agents, and external tools share durable project context;
projects have visible intent, plans, tasks, assets, builds, and decisions;
agents operate through bounded tools and explicit permissions;
SuperMCP integrations connect the agent to creative applications and engines;
every surface presents the same product model at the level appropriate to that surface;
upstream OpenCode improvements can be imported without rewriting UCS product decisions.

The differentiator is the closed feedback loop between intent, agent execution, project state, external creative tools, and review. UCS should optimize for iterative, multi-shot work rather than one-shot code generation.

Current Owner Decisions

These decisions came from the owner interview on 2026-08-10 and should guide the next planning revision:

Ownership: Hybrid, plugin-first. UCS capabilities stay portable; only necessary OpenCode frontend/control-plane behavior is fork-native.
Fork posture: Deliberate private frontend fork. Upstream runtime improvements should continue flowing in through opencode-mirror and fork/local.
Project scope: UCS owns a full durable project/work domain, not only a session UX overlay.
Surface order: Web, TUI, CLI/server, and shared capability work proceed in parallel; Desktop is intentionally last.
Reference integration: unitySuperMCP, integrated with the Unity Editor, is the reference pattern for future integrations such as Unreal, Godot, Roblox, Blender, Figma, Xcode, and Android Studio. It is not a commitment to implement all integrations in the first slice.
Approval: Policy-selected approval gates; projects, agents, and integrations may define different mutation-risk policies.
Initial platform matrix: Web/headless; Linux x86 and ARM; Windows; macOS Apple Silicon only. Desktop packaging is last within that matrix.
Telemetry: Reuse and redirect existing analytics/telemetry into the UCS platform, with no explicit prompt/file/user-content store and a default 30-day retention policy. Provide opt-out to the minimum required for operation and granular opt-in for additional performance, product, and marketing metrics. Web cookie/storage permissions must remain purpose-separated.
UCS feedback: Direct uc-studio project access should be registered so the uc-studio agent can review the contract before Phase 0 closes.

The mixed state-authority answer remains intentionally unresolved; the proposed four-layer model below is the next decision artifact.

Blocking Conflict: Dual Context Ownership

Current Implementation Status

The codebase contains two parallel context management systems. System Context Registry is implemented at packages/core/src/system-context/index.ts via the SystemContext.Source<A> interface, which defines key, codec, load, baseline, update, and removed. The registry service itself is defined at packages/core/src/system-context/registry.ts as @opencode/v2/SystemContextRegistry, with builtins located in packages/core/src/system-context/builtins.ts.

Alongside this, the Context Epoch system is implemented at packages/core/src/session/context-epoch.ts. Database support is established through migrations packages/core/src/database/migration/20260605042240_add_context_epoch_agent.ts and packages/core/src/database/migration/20260622142730_simplify_session_context_epoch.ts.

The Active Code Conflict

A direct conflict exists between the System Context Registry and Magic Context (MC). MC owns the m[0] frozen baseline and the m[1] volatile delta. Because both systems attempt to manage and compact the session context, they compete for ownership. This dual ownership causes severe issues. For example, uc-studio must explicitly disable host compaction by setting compaction.auto: false and compaction.prune: false to prevent dual compaction cycles.

Furthermore, state injections, such as editor selection, Unity play-mode status, project switches, and presence, occur before the cache_control breakpoint. This placement invalidates the prompt cache prefix, destroying prompt caching efficiency.

Resolution Options

Option 1 (Preferred): Magic Context Implements `SystemContext.Source`

Under this option, Magic Context implements the SystemContext.Source interface. Reconciliation runs through a single pipeline. The host manages epoch boundaries, while Magic Context retains ownership of the actual content. This approach preserves prompt-cache prefix stability.

Option 2 (Fallback): Registry Disabled When Magic Context is Active

This option uses a configuration gate to disable the System Context Registry entirely whenever Magic Context is active. Magic Context retains sole ownership of the context.

Option 3 (Documented Alternative): Partition by `SystemContext.Key`

We partition ownership using SystemContext.Key. The System Context Registry owns host-native sources, including current working directory, git status, and editor selection. Magic Context owns memory and history. This option requires a strict guarantee that registry output never precedes the cache_control breakpoint of Magic Context.

Non-Goals And Boundaries

The following are out of scope unless separately approved:

replacing Codex, Claude, or Pi/Senpi frontends;
forcing visual or feature parity across every host;
building a generic plugin marketplace before the core product loop works;
making OpenCode a general-purpose CRM, issue tracker, or enterprise PM suite;
adding cloud sync, billing, analytics, or hosted collaboration as an implicit dependency;
changing the upstream OpenCode public API merely to avoid designing a UCS adapter;
duplicating UCS project state independently in Web, Desktop, TUI, and the plugin;
implementing all SuperMCP integrations before one vertical slice proves the contract;
treating generated SDK files as hand-maintained source;
enabling snapshot tracking by default in deployments (the fork policy is "snapshot": false).

Target Architecture

1. Upstream OpenCode Core

Prefer upstream-compatible use of:

provider and model runtime;
session execution and compaction;
permissions and tool execution;
server lifecycle and HTTP routing;
protocol/schema definitions;
client SDK generation;
baseline TUI and application primitives.

Host-native changes are justified only when UCS requires a capability that cannot be expressed through the public plugin/API seams and the capability is central to the reference product.

2. UCS Capability Plane

This plane should be reusable across hosts and should not import Web, Electron, OpenCode TUI, or host-specific types. It owns the domain vocabulary and behavior for:

agents and categories;
skills and skill discovery;
tools and tool policy;
project plans, tasks, decisions, and milestones;
team coordination and durable mailboxes;
memory/context integration;
UcsExternalApp integration descriptors and lifecycle (via SuperMCP transport where applicable);
provider/model policy and fallback rules;
audit/evidence records;
privacy and telemetry policy.

The existing UCS/OmO package family is evidence that this separation is feasible: shared core packages feed host adapters such as omo-opencode, omo-codex, and omo-senpi.

3. UCS OpenCode Frontend Plane

This plane is intentionally fork-owned:

packages/app/: UCS Web information architecture, session/project workflows, design system, and browser interaction model.
packages/desktop/: Electron shell, native menus, OS integration, window lifecycle, storage, updater, and signed distribution.
packages/tui/ plus OpenCode TUI entrypoints: terminal-first project/session control, compact status, and recovery workflows.
packages/opencode/src/cli/: UCS CLI commands, launch/attach behavior, scripting contracts, and server orchestration.
packages/opencode/src/server/: only the fork-native API/control-plane features that cannot be supplied through the plugin.

The Web and Desktop layers should share product components and data contracts. The TUI should share domain operations and command semantics, but it should not be forced into visual parity with Web/Desktop.

4. Bridge Contracts

The bridge between the planes should be explicit:

OpenCode plugin API for agents, tools, hooks, auth, providers, skills, and runtime transforms.
OpenCode TUI plugin/runtime API for terminal extensions.
HTTP API/protocol/schema for server-backed UCS state and cross-surface events.
Shared SDK/client types generated from source schemas.
SuperMCP event and command contracts for external creative applications.
Versioned capability manifest describing which UCS features a host supports.

Stable Contracts (`@ucs/contracts`)

To ensure interoperability across the ecosystem and insulate the fork from sync breakages, publish @ucs/contracts holding only stable schemas and interfaces:

Plugin ABI: Standard execution contract server(input, options) -> Promise<Hooks>.
Boulder state schema: JSON structure for tracking task execution and recovery (packages/boulder-state + .omo/boulder.json).
Team Mode storage layout: Directory structure and configuration format (~/.omo/teams/{name}/).
Zod v4 config schema: Validation schema for project-level configuration.
Mailbox envelope: Message routing structure containing messageId, correlationId, inReplyToMessageId, intent, priority, and hopPath.
Skill manifest provenance: Security metadata tracking source_repo, source_rev, and per-file sha256 hashes.

Core Dependency Law

All stable contracts must sit at the Schema tier or below. This preserves the strict architecture dependency direction: $$\text{Schema} \rightarrow {\text{Core}, \text{Protocol}} \rightarrow \text{Server}$$ Client runtime code may depend on Schema and Protocol, but never Core or Server. A @ucs/contracts package consumed by both frontend and server must obey this law so running bun run generate from packages/client never breaks.

Unstable Internals (DO NOT FREEZE)

The following internal implementation details are subject to change and must NOT be exposed as stable contracts:

Message layout: Internal m[0] and m[1] message structures (owned by Magic Context).
AFT transport selection: Logic choosing between BridgePool stdio and SubcTransportPool daemon. Expose capabilities, never the transport.
Pipeline internals: Execution flow of the 6-phase agent pipeline. Expose phase names for observability, never let a frontend inject at a phase.
Routing tables: Category and model routing configurations.
Hashline format: The LINE#ID string format used for line-level tracking.

UcsExternalApp Contract

Rather than building Unity-specific frontend plumbing, define a generic UcsExternalApp integration contract with Unity (unitySuperMCP) as implementation #1. This generalizes to Unreal, Godot, Roblox, Blender, Figma, Xcode, and Android Studio.

6 Core Contract Verbs

Every external application adapter implements six standard capabilities:

connect: Establish connection, authenticate, and retrieve remote application state.
status: Query live connection health, active mode, and scene/project context.
capabilities: Inspect supported external actions, tools, and event types.
checkpoint: Trigger a user-visible restore point or snapshot before destructive operations.
blocked-on-human: Signal that the external application is halted waiting for human modal interaction (e.g. Unity Safe Mode dialog, Xcode prompt).
stream-progress: Stream intermediate status for long-running operations (e.g. domain reload, build/compile).

5 Event/State Requirements

Streaming progress: Long operations (domain reload, shader compile) take minutes and invalidate handles. Requires streaming progress events (directly parallel to AFT's bg_events StreamData lane; build one streaming progress abstraction for both).
Modal/blocking interruption: External applications throw OS-level modal dialogs that halt automation. "External app blocked, human input required" must be a first-class agent state (blocked-on-human), not an error.
Connection lifecycle: Mid-session reconnect must be survivable without taking down the OpenCode session or dropping history.
Restore points: Surface checkpoint and restore operations as user-visible restore points.
Background-throttle awareness: External applications (like Unity Editor) throttle CPU/GPU when unfocused. The UI/agent must distinguish a throttled, healthy job from a stalled or hung process to prevent users from killing valid runs.

5. Four-Layer State Authority Model

“A mixture of all four” is workable only if each layer has a narrow authority boundary:

Layer	Authoritative for	Not authoritative for
Repository intent	Project goals, constraints, plans, skills, policy, reusable project configuration	Live session state, secrets, transient process state
OpenCode local runtime	Sessions, messages, tool execution, provider state, local event cursor, ephemeral cache	Cross-machine project truth or marketing/analytics data
UCS coordination store	Work items, milestones, integration registrations, evidence index, cross-session/project coordination, consent ledger	Raw prompts/files unless explicitly approved and separately classified
Optional remote replication	Explicitly selected coordination/telemetry records for approved team or product features	Anything not covered by a declared purpose and retention policy

The first implementation should use an append/reconcile model rather than four competing mutable sources. Each record needs an authority label, stable ID, version, timestamps, provenance, and conflict policy. Remote replication should be a projection or event stream until the owner explicitly chooses it as authoritative for a domain.

6. Privacy And Telemetry Profile

The UCS telemetry design should follow a maintained privacy-control framework rather than inventing an informal “anonymous” label. Use the released NIST Privacy Framework as the current control baseline while tracking the NIST Privacy Framework 1.1 initial public draft, and map product behavior against current ICO and CNIL guidance for data minimization, purpose limitation, retention, consent, cookies/storage, access, deletion, and demonstrable opt-out.

The product profile should be:

Operational minimum by default: crash, startup, version, health, and aggregate performance signals only; no prompts, file contents, tool arguments, auth material, project names, paths, or raw external-tool payloads.
30-day default retention: enforce server-side TTL and document the exact event classes covered; shorter retention is preferred where the purpose allows it.
Opt-out: reduce collection to the minimum required to run, secure, update, and support the product. If a signal is not required for operation, it must stop.
Granular opt-in: separate consent for additional performance diagnostics, product analytics, marketing measurement, and experiments. Do not bundle these purposes.
Web storage/cookies: use purpose-separated consent categories and do not repurpose essential storage as analytics consent.
Desktop/TUI/CLI: provide equivalent settings and an inspectable local consent record even where browser cookies do not apply.
Data-subject controls: define export, deletion, consent withdrawal, and retention-expiry behavior for every remotely replicated record.
Evidence: maintain a telemetry event registry containing purpose, fields, classification, retention, destination, consent requirement, and owner.

This is an engineering target profile, not a legal conclusion. Counsel or a qualified privacy reviewer must validate the final deployment and jurisdictional obligations.

Must-Have Workflows

Tier 1 (Non-negotiable)

Multi-session concurrency with visible session tree: Support one primary agent coordinating with N subagents, rendering the topology clearly in the interface (1 primary + N subagents is the standard pattern; today topology is invisible, which is a major debugging cost).
Background task lifecycle stream: Implement the bg_events StreamData lane, ParentWakeNotifier, and a strict FIFO queue capped at 5 concurrent tasks per model/provider (providerID/modelID).
Durable work state via Boulder: Track execution state using packages/boulder-state and persist progress locally in .omo/boulder.json. Do not invent a second work model.
Policy-matched approvals with audit trail: Enforce permission rules for tool execution with policy match shown, and maintain a tamper-evident audit log of user approvals.
Todo/plan visibility: Expose active plans and todo lists directly in the interface as first-class elements, not buried in chat scrollback.

Tier 2

Cross-project mailbox inbox: Provide a unified view of inbound messages and requests sent between different project agents.
Team Mode topology: Manage agent team configurations and roles stored under ~/.omo/teams/{name}/ (config.json, state.json, mailbox/, tasklist.jsonl, worktrees/).
Evidence browser: Allow users to inspect generated artifacts, logs, and run details stored in .omo/evidence/.
Diff review: Render code changes and file diffs clearly before staging or committing.
Skill/MCP inspector: List active Model Context Protocol servers, registered tools, and loaded skills with provenance (source_repo, source_rev, per-file sha256).

Tier 3 (Deferred)

Model/provider config editors: Graphical interfaces to manage API keys, endpoints, and model parameters.
Telemetry dashboards: Visual charts for token usage, latency, and cost tracking.
Marketplace UI: A browser for discovering and installing community skills or plugins.

Risk Note: Avoid drifting into a generic chat window with buttons. The terminal and web interfaces must render the state that the harness already tracks, rather than inventing separate UI-only state.

Ownership Matrix

Surface	UCS owns	OpenCode upstream owns	Primary gate
Web	Information architecture, navigation, project views, agent/task UX, visual system, workflows	Transport primitives and compatible SDK usage	Unit + browser tests + Playwright evidence
Desktop	Native shell, menus, windows, storage, updater, OS integrations, UCS launch experience	Shared app renderer and server protocol where retained	Typecheck + packaged smoke + platform review
TUI	UCS command vocabulary, project/session control, compact status and recovery affordances	OpenTUI/runtime primitives and compatible baseline	TUI smoke + command behavior evidence
CLI	UCS commands, scripting, attach/serve ergonomics, diagnostics	Provider/session/server primitives	CLI JSON/API smoke and exit-code checks
Server/API	UCS namespaced routes and control-plane features	Existing OpenCode routes and lifecycle	HTTP exercise + schema generation + auth tests
Plugin	UCS capability registration and hook composition	Stable host plugin contract	Hook ordering, lifecycle, and compatibility tests
Other hosts	Shared capability packages and adapter contracts	Host-specific UX and lifecycle	Their own adapter gates; not this roadmap's implementation scope

Plugin And Hook Strategy

Stable V1 compatibility seam

The current V1 plugin type is:

type Plugin = (input: PluginInput, options?: PluginOptions) => Promise<Hooks>

The host loads plugin modules sequentially and triggers returned hooks in order. This is useful for deterministic composition, but the hook object is broad and mutation-oriented. UCS should use one top-level OpenCode plugin entrypoint and compose internal capabilities behind it rather than registering dozens of unrelated top-level plugins.

The fork currently targets the V1 configuration shape (plugin). Upstream V2 uses an ordered plugins field, a new default-export/setup API, and explicitly does not run V1 plugins unchanged. The roadmap must therefore define a versioned adapter boundary rather than silently assuming one config or entrypoint works across both generations.

The stable V1 host automatically installs npm plugin packages into an OpenCode cache, while local plugins are imported directly and do not receive dependency installation automatically. The UCS distribution plan must choose between a packaged adapter, a controlled cache, or a local workspace package; it must not rely on every project independently rebuilding the dependency tree.

V2 adoption posture

The V2 Effect/Promise APIs provide scoped registration, namespaced transforms, sequential runtime hooks, and explicit domain reloads. They are a promising future seam for UCS catalog/agent/command/integration/reference/skill domains, but the roadmap must treat them as version-pinned and compatibility-tested, not as an assumption of stability.

Upstream currently documents V2 as beta: entrypoints, hook shapes, draft shapes, and configuration may change before stable release. Upstream also documents ordered plugin activation, sequential hook execution, scoped cleanup/reload, isolated dependency installation, and the requirement that published plugins target a compatible OpenCode release. These facts make a compatibility layer and release matrix mandatory rather than optional.

Deterministic internal phases

The UCS plugin should own a documented phase graph, for example:

bootstrap/configuration;
capability discovery;
policy and permission guards;
input/session transforms;
tool definition and execution guards;
model/provider transforms;
continuation/compaction;
event publication and project-state updates;
disposal.

Each hook must declare its phase, ordering key, idempotency behavior, failure policy, and observability event. A flat list of hook files is not a sufficient product contract.

Project And Agent Product Model

The roadmap should converge on one domain model, even if the first implementation stores some records in existing OpenCode tables/files.

Project

An intentional creative effort with a root/workspace set, goals, constraints, active plans, assets, integrations, and participants.

Work item

A bounded task or milestone with owner, status, evidence, dependencies, and links to sessions, files, builds, or external-tool actions.

Agent

A named role with model policy, tool permissions, skills, operating mode, and escalation rules. Agents are not merely model aliases.

Skill

A versioned, inspectable operating procedure with explicit tools, inputs, outputs, safety constraints, and verification requirements.

Tool

A capability with a typed contract, permission policy, provenance, timeout/resource budget, and user-visible result semantics.

Integration

An external system connection such as Unity, Unreal, Blender, Figma, Xcode, Discord, or Slack, with explicit capabilities, events, authentication, and failure behavior.

Evidence

A reviewer-readable record of what was run, what was observed, what it proves, and what was omitted. Evidence is part of project trust, not only CI output.

The first implementation must decide whether these records are authoritative in OpenCode's database, UCS-owned files/database, or an external control plane. The roadmap deliberately does not choose that without owner approval.

Roadmap Phases

The roadmap collapses the prior eight-phase plan into six phases. The reorder is deliberate: server substrate precedes any Web work, the first shippable slice is read-only observability (cheap to prove, safe to merge), write actions and approvals are isolated into their own phase, external-app integration (Unity and successors) is generalized under one UcsExternalApp contract, and Desktop is sequenced last alongside release operations. Every deliverable from the old Phase 0–7 plan is carried forward; see Deliverable Mapping.

Phase 0: Alignment, Contracts, And Conflict Unblock

Purpose: Resolve every decision and structural conflict that would otherwise force rework, and freeze the shared contracts before any surface or server code is written. Absorbs old Phase 0 (Alignment And Contract Freeze) and old Phase 1 (Fork Inventory And Divergence Budget).

Deliverables:

@ucs/contracts package: a single, versioned, host-neutral home for shared terminology, route/command IDs, domain types, the namespaced ucs API surface rule, and the capability manifest. All later phases import contracts from here rather than redeclaring them.
Dual context-ownership conflict resolved (blocking): packages/core/src/system-context/index.ts and packages/core/src/session/context-epoch.ts currently both claim authority over "context." Choose one owner before any write path exists:
- Option 1 (preferred): make session/context-epoch.ts the single authority for live, per-session context, and demote system-context/index.ts to a read-only projection/provider that feeds epochs but never owns session context. One owner, one write path, consistent with the four-layer authority model and the append/reconcile principle.
- Option 2: retain both owners behind an explicit reconciliation layer (more moving parts, higher lost-update and migration risk).
- Evidence for the chosen option must account for the existing epoch migrations 20260605042240_add_context_epoch_agent and 20260622142730_simplify_session_context_epoch.
UCS-agent feedback returned and attached to the roadmap (satisfied 2026-08-10; see Evidence Base).
Product vocabulary and non-goals approved.
Source of truth for project/work state chosen (resolves old P0 "state authority" and the context-ownership conflict together).
Plugin-first versus host-native criteria approved.
Supported surfaces and platform matrix chosen.
Privacy, telemetry, and external-network policy chosen.
Ownership map for Web, Desktop, TUI, CLI, Server/API, Plugin API, Protocol/Schema, and generated SDKs (from old P1).
Divergence ledger with owner, rationale, upstream status, merge risk, and rollback plan (from old P1).
Namespaced-surface rule: all UCS API additions use a ucs surface rather than modifying unrelated upstream semantics (folded into @ucs/contracts).
Sync rehearsal procedure using opencode-mirror → fork/local, exercised against packages/opencode/test/fork-sync-model.test.ts.
Explicit generated-file policy: source edits first, regeneration second, generated outputs never hand-edited.

Gate: No implementation begins until the P0 questions are answered, the UCS agent confirms the capability boundary, the dual context-ownership conflict is resolved with recorded rationale, @ucs/contracts is published, and a clean upstream merge rehearsal passes.

Phase 1: Server Substrate

Purpose: Stand up only the server-side state, topology, and task-state endpoints the product model needs, and regenerate the client from source schemas — before any Web surface consumes them. Absorbs old Phase 5 (UCS Server And Control Plane).

Deliverables:

Namespaced UCS HTTP API groups and schemas (built on the @ucs/contracts surface).
Topology endpoints: project/workspace/session topology and relationships.
Task-state endpoints: project/work/integration state with authorization boundaries.
Event-stream semantics for session, work, integration, and evidence updates.
Client regeneration: generated client SDK updated from source protocol/schema changes; no hand edits to generated output.
Placement decision (2026-08-11): the namespaced ucs API group lives in the instance HttpApi (packages/opencode/src/server/routes/instance/httpapi/groups/ucs.ts), not in packages/protocol's makeApiFromGroup. Rationale: (1) UcsGroup endpoints read instance-owned services (Session.Service, SessionStatus.Service, Workspace.Service, EventV2Bridge.Service) that packages/server cannot reach — protocol handlers are limited to Core services, so a protocol-level UCS group could not back the topology/task-state surface; (2) the modern client SDK (packages/client codegen) only generates from protocol groups, so instance routes are not SDK surface; (3) this keeps packages/protocol and packages/core import-free of fork-owned packages — @ucs/contracts remains at the Schema tier, depended on by the server and by fork surfaces, never by Core/Protocol. Client regeneration is still exercised as a gate (packages/client generate must produce a zero diff; the legacy SDK is regenerated from the PublicApi OpenAPI, which includes the instance routes).
Migration and rollback policy for persisted data.
Headless server mode suitable for Desktop, Web, CLI, and remote operation.
CLI/server command and API naming conventions (carried from old P2, since naming rides the substrate).

Gate: API exercise coverage, authentication/authorization tests, generated-SDK verification (regenerated, diff-reviewed, no manual edits), a migration test, and an upstream merge rehearsal.

Phase 2: Read-Only Web Vertical Slice

Purpose: Ship the first end-to-end Web slice as read-only multi-session observability, and prove — with hard evidence — that driving a session through Web does not degrade provider prompt caching relative to the TUI. This is the cheapest slice that proves the substrate, the Web shell, and cache-safe transport in one shot.

Slice definition: read-only, multi-session observability on Web — list active/recent sessions, inspect messages, tool calls, token usage, and live session/project state over the Phase 1 event stream, with no write actions.

Deliverables:

Shared domain navigation (Home, Projects, Work, Agents, Skills, Tools, Integrations, Sessions, Builds, Settings) in read-only form (from old P2 navigation).
Web design-system foundation and responsive layout (from old P2).
Multi-session observability view: concurrent sessions rendered from the Phase 1 topology and event stream (from old P6 Web "multi-session workflows," read-only portion).
Read-only project view and work-item view fed by Phase 1 task-state endpoints (read portion of old P3 "one project view / one work-item view").
Session and project state visible in Web and available through CLI/server (from old P3).
TUI read/status parity for the same domain operations, used as the cache baseline (from old P2 TUI command map).
Prompt-cache proof (acceptance-critical): a session driven through Web reports the same cache_read ratio as the identical session driven through the TUI. Capture provider cache_read / cache_write token counts on identical prompt prefixes over both surfaces; the Web-driven cache_read ratio must be at parity with the TUI baseline (no cache-busting regression introduced by the Web transport or request shaping).

Gate: Package-local typecheck; targeted unit/browser tests; Playwright evidence of read-only multi-session observation against a live server; and a recorded cache-parity measurement showing Web cache_read ratio ≥ TUI baseline for the same session. Desktop is explicitly deferred to Phase 5 and must consume these contracts, not define them.

Phase 3: Write Actions & Approvals

Purpose: Introduce mutation to the read-only slice under policy-matched approvals — prompts, edits, and other write actions — with the approval decision as a first-class, policy-selected step.

Deliverables:

Policy-matched approval gates: project-, work-item-, tool-call-, and policy-level approval resolution (realizes old P0 "policy-selected approval" and old P6 approval affordances).
Write actions on the Phase 2 views: send prompts, apply edits, mutate project/work state through authorized Phase 1 endpoints (write portion of old P3/P6 project and work-item views).
Approval UX on Web and approval/recovery affordances on TUI (write/approval portion of old P6 TUI completion).
Consumes the tool permission/resource policy defined in Phase 4's registries where available; where a policy is not yet registered, writes remain gated by default-deny.
CLI/server write and operational commands for the same actions (write portion of old P6 CLI).

Gate: Approval-policy tests (grant/deny/escalation paths), write-path authorization tests, Playwright evidence of an approved write applied end-to-end, and a default-deny test proving unapproved mutations cannot reach external state.

Phase 4: UcsExternalApp Integration

Purpose: Prove the external-application loop with a real integration and turn the slice into reusable UCS capabilities. Generalizes the old Unity slice under one UcsExternalApp contract and absorbs the capability-plane work. Absorbs old Phase 3 (First Vertical Slice / Unity) and old Phase 4 (Capability Plane Integration).

Reference slice: project → plan → agent task → policy-approved bounded action through a UcsExternalApp adapter → external event → review/evidence → updated project state. Unity via unitySuperMCP is the first concrete UcsExternalApp adapter, and the contract must be generic enough to template Unreal, Godot, Roblox, Blender, Figma, Xcode, and Android Studio.

Deliverables:

UcsExternalApp integration contract: typed action/event schema, authentication, capability descriptor, and failure behavior (generalized from old P3 SuperMCP contract).
Unity unitySuperMCP adapter implementing the contract end-to-end (old P3 slice).
One opinionated agent role with a small approved skill set driving the external action (old P3).
One review/evidence flow for external actions (old P3).
Versioned agent/category registry (old P4).
Skill registry with source, version, tool requirements, and verification metadata (old P4).
Tool registry with permission and resource policy — the policy source consumed by Phase 3 approvals (old P4).
Team/task coordination contract (old P4; contract seed from @ucs/contracts).
Memory/context integration contract, aligned with the Phase 0 context-ownership decision (old P4).
Provider/model policy and fallback contract (old P4).
OpenCode adapter with deterministic hook phases (old P4).
Adapter conformance fixtures other hosts can consume without importing OpenCode UI/runtime code (old P4).

Gate: Real end-to-end execution against unitySuperMCP and the Unity Editor, with isolated test state, recorded evidence, and no mocks standing in for the critical external action; plus adapter conformance fixtures passing and shared packages remaining host-neutral so Codex/Claude/Pi-Senpi adapters still build against their own contracts.

Phase 5: Desktop Last & Release Operations

Purpose: Complete the Desktop surface and make the fork maintainable as a product. Absorbs old Phase 6 (Desktop portion of Surface Completion) and old Phase 7 (Upstream And Release Operations).

Deliverables:

Desktop (last): Electron shell, native menus, windows, storage, updater, deep links, terminal/PTY integration, platform permissions, and platform-specific UX for macOS Apple Silicon, Linux, and Windows (old P6 Desktop). Desktop consumes the Phase 0 shell contract and the Phase 1–4 web/server/capability contracts; it does not define domain authority.
Desktop shell contract realized (menus, windows, deep links, notifications, storage, updater) from old P2, now implemented rather than only specified.
Final TUI/CLI surface completion polish layered on the Phase 2–4 functional surfaces (remaining old P6 TUI/CLI completion).
Regular upstream sync rehearsal and merge-risk report (old P7).
Release manifest identifying upstream, UCS capability, and UCS frontend versions (old P7).
Compatibility matrix for OpenCode host/plugin API versions (old P7).
Compatibility matrix covering the stable V1 adapter and beta V2 adapter separately; V2 changes require a pinned OpenCode release and a published compatible plugin build (old P7).
Binary build and artifact smoke for supported platforms (old P7).
Rollback procedure for frontend, plugin, API, and data migrations (old P7; data-migration rollback seeded in Phase 1).
Deployment defaults including "snapshot": false (old P7).
Release notes distinguishing upstream changes from UCS changes (old P7).
Telemetry/privacy target profile and retention/consent audit — policy chosen in Phase 0, audited here (old P7).

Gate: A signed/verified artifact; real server bootstrap; Web/Desktop/TUI/CLI smoke coverage; packaged Desktop smoke on each supported platform; accessibility/keyboard review for Web/Desktop; and a documented rollback path.

Deliverable Mapping: Old Phases 0–7 → New Phases 0–5 (no loss)

Every old deliverable is carried into the six-phase model. "Primary" is the phase that owns the deliverable; "Also in" notes phases where a precursor or split portion lands.

Old phase	Old deliverable	Primary new phase	Also in
P0 Alignment	UCS-agent feedback returned and attached	P0	—
P0 Alignment	Product vocabulary and non-goals approved	P0	—
P0 Alignment	Source of truth for project/work state chosen	P0 (conflict unblock)	—
P0 Alignment	Plugin-first vs host-native criteria approved	P0	—
P0 Alignment	Supported surfaces and platform matrix chosen	P0	—
P0 Alignment	Privacy/telemetry/external-network policy chosen	P0	P5 (audit)
P0 Alignment	Gate: P0 questions answered + capability boundary	P0	—
P1 Inventory	Ownership map (all surfaces + SDKs)	P0	—
P1 Inventory	Divergence ledger	P0	—
P1 Inventory	Namespaced `ucs` API rule	P0 (`@ucs/contracts`)	—
P1 Inventory	Sync rehearsal `opencode-mirror`→`fork/local`	P0	P5
P1 Inventory	Generated-file policy	P0	P1 (SDK), P5
P1 Inventory	Gate: clean merge rehearsal + host-native answers	P0	—
P2 Frontend	Shared domain navigation	P2 (read-only)	P3 (write)
P2 Frontend	Shared terminology + route/command IDs	P0 (`@ucs/contracts`)	—
P2 Frontend	Web design-system foundation + responsive layout	P2	—
P2 Frontend	Desktop shell contract	P5	P0 (contract spec)
P2 Frontend	TUI command map	P2 (read baseline)	P3 (write/approvals)
P2 Frontend	CLI/server command + API naming conventions	P1	—
P2 Frontend	Gate: shell with one path on Web/TUI/CLI (Desktop deferred)	P2	P5 (Desktop)
P3 Slice	Unity `unitySuperMCP` → Unity Editor slice	P4 (`UcsExternalApp`)	—
P3 Slice	One project view + one work-item view	P2 (read)	P3 (write), P4 (integration)
P3 Slice	One opinionated agent role + small skill set	P4	—
P3 Slice	One SuperMCP integration (typed action/event)	P4	—
P3 Slice	One review/evidence flow	P4	P2 (read view)
P3 Slice	Session/project state in Web + via CLI/server	P2	P1 (endpoints)
P3 Slice	Gate: real end-to-end vs Unity, no mocks	P4	—
P4 Capability	Versioned agent/category registry	P4	—
P4 Capability	Skill registry (source/version/verification)	P4	—
P4 Capability	Tool registry (permission + resource policy)	P4	P3 (approvals consume)
P4 Capability	Team/task coordination contract	P4	P0 (contract seed)
P4 Capability	Memory/context integration contract	P4	P0 (context-owner decision)
P4 Capability	Provider/model policy + fallback contract	P4	—
P4 Capability	OpenCode adapter with deterministic hook phases	P4	—
P4 Capability	Adapter conformance fixtures	P4	—
P4 Capability	Gate: reference-complete + host-neutral packages	P4	—
P5 Server	Namespaced UCS HTTP API groups + schemas	P1	—
P5 Server	Project/work/integration endpoints + authz (topology + task-state)	P1	—
P5 Server	Event-stream semantics	P1	P2 (consumer)
P5 Server	Generated client SDK updates (client regeneration)	P1	—
P5 Server	Migration + rollback policy for persisted data	P1	P5 (rollback)
P5 Server	Headless server mode	P1	—
P5 Server	Gate: API/authz/SDK/migration tests + merge rehearsal	P1	—
P6 Surface	Web: full nav, review, multi-session workflows	P2 (multi-session, read)	P3 (write/review)
P6 Surface	Desktop (last): native workspace, updater, packaging, platform UX	P5	—
P6 Surface	TUI: switching, status, agent/task control, approvals, recovery	P3 (approvals/control)	P2 (read), P5 (polish)
P6 Surface	CLI/server: automation, JSON, attach/serve, diagnostics, import/export	P1 (substrate)	P3 (write ops), P5 (polish)
P6 Surface	Gate: per-surface QA + packaged Desktop smoke	Split	P2/P3/P4 per surface; P5 (Desktop)
P7 Release	Regular upstream sync rehearsal + merge-risk report	P5	P0 (first rehearsal)
P7 Release	Release manifest (upstream/capability/frontend versions)	P5	—
P7 Release	Compatibility matrix for host/plugin API versions	P5	—
P7 Release	V1 vs V2 adapter compatibility matrix (separate)	P5	—
P7 Release	Binary build + artifact smoke for supported platforms	P5	—
P7 Release	Rollback procedure (frontend/plugin/API/data)	P5	P1 (data rollback)
P7 Release	Deployment defaults incl. `"snapshot": false`	P5	—
P7 Release	Release notes: upstream vs UCS changes	P5	—
P7 Release	Telemetry/privacy profile + retention/consent audit	P5	P0 (policy)
P7 Release	Gate: signed artifact + bootstrap + smoke + rollback	P5	—

Upstream Sync Strategy

Continue the existing fork model:

opencode-mirror: pristine upstream mirror;
fork/local: permanent UCS customization layer.

Add a third conceptual classification inside fork/local:

Upstream-compatible: changes that can be proposed upstream or merged with low conflict.
UCS capability: reusable packages/adapter logic that should remain separate from frontend code.
UCS frontend: deliberate fork-owned product behavior.

Every fork-local change should record one classification. The frontend plane is allowed to diverge, but it must not silently pull capability-plane concerns into packages/app or Electron-only code.

Merge-risk rules

Core vs. Fork vs. Adapter Separation: Core never imports from the fork. If non-OpenCode harnesses need it -> Core. If a plugin hook can do it -> Adapter (omo-opencode). If it needs rendering or a new HTTP endpoint -> Fork.
Fork Diff Size Metric: Track fork diff size as a tracked release metric (script/fork-sync-exclusions encodes permanent divergence; anything not listed should be pushed down).
Versioning Scheme: Keep upstream's version as base with a UCS suffix (1.18.15+ucs.N) so upstream lineage stays legible in every artifact. @ucs/contracts is semver'd independently.
Static Egress Audit for Telemetry: No third-party telemetry egress, with zero exceptions for "anonymous" stats. A static egress audit runs in packages/opencode/test/fork-sync-model.test.ts (extended to frontend bundles). Zero third-party egress coexists with the internal UCS operational telemetry profile defined under Privacy Profile.
Vendored Mirrors Constraint: aft and magic-context are vendored mirrors updated via script/sync-cortexkit.sh. Local patches get reverted on next sync. Any feature requiring an AFT or Magic Context change MUST land upstream in the cortexkit repositories first.
Prefer new namespaced files and route groups over broad edits to upstream files.
Keep public protocol/API changes additive and generated from source.
Keep UCS visual design and navigation changes localized to packages/app, packages/desktop, and TUI feature/plugin surfaces.
Keep host-specific code out of shared packages.
Re-run generation after protocol/server changes.
Rehearse merges before large frontend refactors are allowed to accumulate.
Preserve protected fork files and exclusion manifests.
Never let a release watcher dynamically rewrite the architecture during a build.
Avoid per-project dependency installation and generated .opencode/package.json churn where a packaged, version-pinned binary or centrally managed plugin cache is sufficient; the stable host's default npm cache is ~/.cache/opencode/node_modules, while local plugin dependencies must be made visible from the plugin configuration directory.
Keep Desktop behind the shared Web/TUI/CLI/server contracts; do not let Electron IPC or native storage become the domain authority.

Verification Model

Every phase must produce evidence, not only code or passing unit tests.

Required evidence categories

Contract: types/schema/API shape and compatibility.
Behavior: real user-facing or agent-facing execution.
Isolation: test state, XDG/config/database separation, and unchanged host state.
Integration: external SuperMCP or provider interaction where applicable.
Merge: upstream sync rehearsal and generated-file cleanliness.
Operations: artifact startup, health, logs, and rollback behavior.

Surface gates

Web: package-local typecheck, targeted unit/browser tests, Playwright behavior and visual evidence.
Desktop: renderer/main/preload typecheck, packaged build, native shell smoke, updater/deep-link/IPC checks.
TUI: package-local typecheck/tests, tmux or equivalent smoke, key command behavior, recovery checks.
CLI/server: package-local typecheck/tests, JSON contract checks, server bootstrap, HTTP API exercise, and exit-code assertions.
Plugin: hook-order tests, duplicate-load tests, disposal tests, capability/permission tests, and live host smoke.
Protocol/API: source-schema tests, generated SDK diff review, authorization tests, migration tests.

Risk Register

Risk	Consequence	Mitigation
Plugin/host boundary blur	Permanent merge burden and duplicated logic	Require plugin-first/host-native justification per feature
Web/Desktop/TUI treated as one product surface	Incomplete UX and untestable milestones	Separate ownership and gates per surface
UCS project state duplicated across systems	Conflicts, migration pain, unclear authority	Decide one source of truth in Phase 0
Dual context-ownership conflict ships unresolved (Severity: Blocking)	Live/system context desync, lost updates, and unsafe multi-session writes across `system-context` and `session/context-epoch`	Resolve in Phase 0 before any write path. Prefer Option 1: session `context-epoch` is the single authority; `system-context` demoted to a read-only projection. Validate against migrations `20260605042240` and `20260622142730`.
V2 plugin API changes upstream	Adapter breakage	Version pin, compatibility layer, conformance tests
API/schema divergence	Generated SDK and server drift	Source-first edits and mandatory generation gate
SuperMCP integration assumptions	Expensive rework or unsafe actions	One real vertical slice and explicit capability contracts
Frontend fork grows without merge budget	Upstream sync becomes unaffordable	Divergence ledger and regular merge rehearsal
Desktop native scope expands	Signing/platform delays	Web-first shared capability, native-only behavior by exception
TUI parity demand	Separate frontend becomes a second product	Define TUI as control/status surface unless approved otherwise
Privacy/telemetry ambiguity	Loss of trust and accidental data exposure	Phase 0 data-boundary and telemetry decision
~~Missing UCS-agent feedback~~ — Resolved 2026-08-10	Roadmap would encode wrong cross-project assumptions	Closed: feedback received (msg `134fb143-3462-4234-b928-93b1d53806fe`, trace `.omo/mailbox-trace.jsonl`) and incorporated into this revision
Snapshot storage recurrence	Boot-drive exhaustion during tests/deployments	Keep `"snapshot": false` as deployment default and verify it operationally
Per-project plugin dependency churn	Hundreds of generated dependency trees, slow startup, or version mismatch	Package the UCS adapter, pin host/plugin versions, isolate caches, and add disk-growth smoke checks
Ambiguous mixed state authority	Lost updates, conflicting records, impossible migrations	Assign every record to one authority layer and use explicit projections/reconciliation
Over-broad telemetry	Privacy, trust, and compliance exposure	Classify events, prohibit content-bearing fields, enforce 30-day TTL, and audit opt-out/consent

Owner Interview: Decisions Required

These questions are intentionally extensive because each answer changes architecture, ownership, or verification.

P0: Roadmap blockers

Is UCS project/work state authoritative in OpenCode's database, UCS-owned storage, git-tracked files, or a remote control plane?
Does UCS own durable project management, or only the UX over existing OpenCode sessions/workspaces?
Are Web, Desktop, TUI, CLI, server/API, and plugin API all first-class in the first release, or is there an ordered priority?
Should the OpenCode fork remain compatible with upstream OpenCode installations, or only this fork?
Which features must be plugin-first, and which are explicitly allowed to be host-native fork code?
May UCS change the public OpenCode protocol/plugin API, or must all changes remain additive and namespaced?
What is the desired upstream posture: upstreamable changes, long-lived private divergence, or a deliberate mixture?
What exactly must the uc-studio agent sign off on before Phase 0 closes?
Decision: Register the uc-studio project for direct agent-to-agent feedback; this remains an environment/allowlist prerequisite before Phase 0 closes.
Which data must never leave the local machine, beyond the telemetry exclusions already recorded above?

P1: Product scope

Is “frontend ownership” design ownership, implementation ownership, release ownership, or all three?
Should Desktop be a native shell around the Web product, or have native-only UCS workflows?
Should TUI provide project/work control only, or full project-management parity?
Should CLI expose UCS domain commands, or only launch/attach/serve and diagnostics?
Should UCS projects map one-to-one to OpenCode projects, or can one UCS project span repositories/workspaces?
Is portfolio/multi-project navigation required?
Are builds, assets, designs, and external-tool artifacts first-class UCS records or links only?
Is human approval a project-level, work-item-level, tool-call-level, or policy-level concept?
Which agent roles are opinionated UCS defaults, and which remain user-configurable?
Are skills curated by UCS, user-authored, project-authored, or all three with precedence rules?
Are tools allowed to mutate external applications automatically, or must SuperMCP actions be approval-gated?
Which integrations are required for the first vertical slice: Unity, Unreal, Godot, Roblox, Blender, Figma, Xcode, Android Studio, Discord, Slack, or another target?
Is cross-app state synchronization live, event-driven, periodically reconciled, or manually refreshed?
Does UCS need offline-first behavior?
Is cloud/remote server operation required in the first release?

P2: Delivery and operations

Which platforms are supported at release: macOS, Linux, Windows, Web-only, headless server?
What is the minimum artifact verification expected before a release is trusted?
Should every milestone include an upstream merge rehearsal?
What is the rollback strategy for schema/API changes?
What is the acceptable frontend divergence budget per upstream release?
Who owns UX/design review for fork-local frontend changes?
Who owns UCS capability contracts when an external host adapter disagrees with OpenCode?
What evidence must be retained, for how long, and where?
Is telemetry completely disabled, locally recorded only, or opt-in and anonymized?
What is the release-channel model for upstream, UCS capability, and UCS frontend versions?
Does the deployment policy require snapshot: false in every generated config, container, and packaged desktop default?
Which existing UCS QA scripts are safe to run during roadmap validation, given the prior disk-space incident?

UCS-Agent Feedback Gate

Status (2026-08-10): Satisfied. The uc-studio agent returned structured feedback as mailbox message 134fb143-3462-4234-b928-93b1d53806fe (trace in .omo/mailbox-trace.jsonl). This gate is met; its content is incorporated into the six-phase model and the Risk Register above. The document is no longer blocked on feedback, but remains a strategy draft until the remaining approval gates (see Approval State) are cleared.

Before implementation begins, obtain a response from the uc-studio agent covering:

must-have UCS user, agent, and project workflows;
stable UCS contracts and package ownership;
required SuperMCP integrations and event/state flows;
what belongs in UCS core, the OpenCode fork, or an adapter;
release/versioning and upstream-sync expectations;
non-negotiable UX decisions per surface;
privacy, telemetry, and security constraints;
first vertical-slice and production-readiness acceptance criteria.

Until that response exists, this document is a strategy draft, not a frozen implementation plan.

Recommended Immediate Sequence

Done (2026-08-10): direct uc-studio-agent feedback received and attached (mailbox message 134fb143-3462-4234-b928-93b1d53806fe, trace .omo/mailbox-trace.jsonl).
Resolve the dual context-ownership conflict (Option 1 preferred): make packages/core/src/session/context-epoch.ts the single authority for live per-session context and demote packages/core/src/system-context/index.ts to a read-only projection, validating against migrations 20260605042240 and 20260622142730.
Resolve the remaining P0 questions — upstream compatibility, API-change policy, and telemetry data boundaries — and publish @ucs/contracts.
Convert this document into a decision-complete implementation plan starting with the read-only Web observability slice and its cache_read parity test, with explicit file/package targets.
Create the divergence ledger before modifying frontend or protocol code.
Implement Phase 1 (Server Substrate), then the Phase 2 read-only Web slice, with real cache-parity evidence and an upstream merge rehearsal before adding write actions.

Research Sources

Primary upstream sources consulted:

Repository-local sources:

AGENTS.md
script/fork-sync.sh
script/fork-sync-exclusions
packages/plugin/src/index.ts
packages/plugin/src/v2/effect/README.md
packages/plugin/src/v2/promise/README.md
packages/app/
packages/desktop/
packages/tui/
packages/opencode/src/cli/
packages/opencode/src/server/
packages/protocol/
packages/schema/
packages/client/src/generated/
/Volumes/Topper2TB/Git/uc-studio/README.md
/Volumes/Topper2TB/Git/uc-studio/AGENTS.md
/Volumes/Topper2TB/Git/uc-studio/packages/omo-opencode/
packages/core/src/system-context/index.ts
packages/core/src/session/context-epoch.ts
packages/core/src/database/migration/20260605042240_add_context_epoch_agent.ts
packages/core/src/database/migration/20260622142730_simplify_session_context_epoch.ts
packages/opencode/test/fork-sync-model.test.ts
.omo/mailbox-trace.jsonl

Approval State

Not yet approved for implementation. Gate status as of 2026-08-10:

Satisfied — direct uc-studio-agent feedback. Received as mailbox message 134fb143-3462-4234-b928-93b1d53806fe (trace .omo/mailbox-trace.jsonl) and incorporated.
Outstanding — P0 owner questions. Remaining blockers: state authority and, specifically, the dual context-ownership conflict between packages/core/src/system-context/index.ts and packages/core/src/session/context-epoch.ts (Option 1 preferred), plus upstream-compatibility posture, API-change policy, and telemetry data boundaries.
Outstanding — first vertical slice and surface priority. Confirm the first slice as the read-only Web observability slice (Phase 2) with the cache_read parity acceptance test, ahead of write actions (Phase 3) and UcsExternalApp integration (Phase 4).

Implementation may begin only after gates 2 and 3 are cleared and the Phase 0 gate (including the context-ownership resolution and a clean merge rehearsal) passes.

FilesExpand file tree

ROADMAP.md

Latest commit

History

ROADMAP.md

File metadata and controls

Ultra Creative Studio OpenCode Fork Roadmap

Executive Decision

Evidence Base

Feedback status

Product Thesis

Current Owner Decisions

Blocking Conflict: Dual Context Ownership

Current Implementation Status

The Active Code Conflict

Resolution Options

Option 1 (Preferred): Magic Context Implements SystemContext.Source

Option 2 (Fallback): Registry Disabled When Magic Context is Active

Option 3 (Documented Alternative): Partition by SystemContext.Key

Non-Goals And Boundaries

Target Architecture

1. Upstream OpenCode Core

2. UCS Capability Plane

3. UCS OpenCode Frontend Plane

4. Bridge Contracts

Stable Contracts (@ucs/contracts)

Core Dependency Law

Unstable Internals (DO NOT FREEZE)

UcsExternalApp Contract

6 Core Contract Verbs

5 Event/State Requirements

5. Four-Layer State Authority Model

6. Privacy And Telemetry Profile

Must-Have Workflows

Tier 1 (Non-negotiable)

Tier 2

Tier 3 (Deferred)

Ownership Matrix

Plugin And Hook Strategy

Stable V1 compatibility seam

V2 adoption posture

Deterministic internal phases

Project And Agent Product Model

Project

Work item

Agent

Skill

Tool

Integration

Evidence

Roadmap Phases

Phase 0: Alignment, Contracts, And Conflict Unblock

Phase 1: Server Substrate

Phase 2: Read-Only Web Vertical Slice

Phase 3: Write Actions & Approvals

Phase 4: UcsExternalApp Integration

Phase 5: Desktop Last & Release Operations

Deliverable Mapping: Old Phases 0–7 → New Phases 0–5 (no loss)

Upstream Sync Strategy

Merge-risk rules

Verification Model

Required evidence categories

Surface gates

Risk Register

Owner Interview: Decisions Required

P0: Roadmap blockers

P1: Product scope

P2: Delivery and operations

UCS-Agent Feedback Gate

Recommended Immediate Sequence

Research Sources

Approval State

Option 1 (Preferred): Magic Context Implements `SystemContext.Source`

Option 3 (Documented Alternative): Partition by `SystemContext.Key`

Stable Contracts (`@ucs/contracts`)