openwork/prd-workspaces-jit.md

PRD — Folder-Scoped Workspaces (JIT) + Starter Workspace (OpenWork)

Summary

OpenWork currently asks users to pick a folder at app start (Host onboarding) and pre-authorize access up front. This is safe, but it’s the wrong moment: users just want to try the product and start a task.

This PRD reframes “workspace” around OpenCode primitives:

• Primary primitive: folders. A workspace is a folder.
• Workspace scope is already defined by OpenCode’s project model:
  • Plugins/MCP live in project opencode.json
  • Skills live in project .opencode/skill
  • The OpenCode client already accepts a directory (folder) to scope project behavior

What changes

1. Just-in-time (JIT) workspace selection: pick a workspace when you start work (new session / first prompt / run template), not at app launch.
2. Starter Workspace: OpenWork ships/creates a “ready-to-run” default folder-workspace so new users can start immediately.
3. Workspace templates: creating a workspace is “choose a folder + apply a template” (writes OpenCode-native files like opencode.json and .opencode/*).
4. JIT folder expansion: when a task needs access to a new folder, OpenWork offers “Allow once / Add to workspace / Deny”.

This keeps least-privilege, but moves permissions to the moment of intent.

Design Principle (Guiding)

OpenWork should prefer OpenCode primitives before inventing new ones.

For “workspaces”, that means:

• A workspace should map to a real folder.
• Workspace configuration should live in existing OpenCode surfaces:
  • opencode.json (project scope plugins/MCP)
  • .opencode/skill (project scope skills)
• Any OpenWork-only metadata should still live inside the folder (e.g. .opencode/openwork.json) rather than a separate global database.

Problem

The current onboarding step “Authorized Workspaces” front-loads decisions that users don’t understand yet:

• Users want to try OpenWork without choosing a folder.
• Users often don’t know what folder they need until they write the task.
• Users commonly work across multiple folders (repo + docs + downloads), which doesn’t fit a single “project dir” prompt.

The result: a premium UI with an early “developer cliff”.

Goals

• Remove upfront folder selection from first-run Host onboarding.
• Treat “workspace” as a folder-scoped OpenCode project.
• Provide a Starter Workspace that works out-of-the-box.
• Let users create many workspaces quickly using templates.
• Support multiple authorized folders per workspace and add them JIT.
• Keep parity with OpenCode behavior and config surfaces.

Non-goals

• Replacing OpenCode’s permission system.
• Multi-user workspace sharing and sync (future).
• Full IDE-style project management.

Current Constraints

• OpenWork effectively has two layers of access control:

  1. OS/native folder picking and OpenWork-managed allowed roots
  2. OpenCode permission requests surfaced via events

• Host mode currently expects a project directory early.

Proposal

1) Workspace = Folder + OpenCode config

A workspace is identified by its folder path (primary directory).

Within that folder:

• Plugins/MCP configuration: opencode.json
• Skills: .opencode/skill/*
• OpenWork metadata (optional): .opencode/openwork.json

This aligns with existing OpenCode project scoping (directory), and keeps workspaces reconstructable.

2) Starter Workspace (first-run default)

On first Host launch, OpenWork creates (or initializes) a default workspace folder (the “Starter Workspace”).

Suggested folder location (app-managed, no user picker):

• macOS: ~/Library/Application Support/OpenWork/workspaces/starter
• Linux: ~/.local/share/openwork/workspaces/starter
• Windows: %APPDATA%\\OpenWork\\workspaces\\starter

The Starter Workspace is a real folder workspace with a template applied:

• opencode.json includes a recommended “starter” plugin set
  • includes different-ai/opencode-scheduler by default
• .opencode/skill can optionally include a small set of curated starter skills (future)

This means:

• The user can reach the dashboard and run a first task without selecting any folder.
• The workspace model is visible and consistent from minute one.

3) Workspace templates (folder-native)

Creating a workspace becomes:

1. Pick or create a folder (JIT)
2. Choose a template
3. OpenWork writes/updates OpenCode-native files in that folder

Template examples:

• Starter (recommended)
  • installs/enables different-ai/opencode-scheduler
  • optionally suggests the browser/plugin set (future)
• Minimal
  • no plugins; purely connect and run
• Automation
  • scheduler + any supported automation plugins

The important rule: templates should not create a parallel config system. They should materialize into opencode.json and .opencode/*.

4) JIT workspace selection moments

Workspace selection happens when:

• starting a new session
• sending the first prompt (if no session)
• running a template

If there is no active workspace, OpenWork shows a lightweight “Workspace Picker” sheet:

• Recent workspaces (folders)
• Starter Workspace (pinned)
• “New workspace…”
• “Quick task (no file access)” (uses Starter Workspace in read-only/no-extra-folders mode)

5) JIT folder expansion (“Add to workspace”)

When the agent needs to read/write outside currently authorized roots, OpenWork prompts:

• Allow once (session-only)
• Add to workspace (persist folder into workspace’s authorized folder list)
• Deny

Storage:

• authorized folders are recorded in .opencode/openwork.json inside the workspace folder

This keeps the “workspace = folder” model intact while still allowing multi-folder workflows.

6) Plugins + Skills scoping becomes workspace-first

Plugins tab:

• Default scope = current workspace (<workspace>/opencode.json)
• Secondary scope = global (~/.config/opencode/opencode.json)

Skills tab:

• Default install target = current workspace (<workspace>/.opencode/skill)
• Optional future: global skills (explicit)

UX / UI Elements

A) Workspace Chip (always visible)

A compact chip in the dashboard header and prompt bar:

• shows active workspace name/folder
• tap to open workspace picker

B) Workspace Picker (sheet)

• Recent + pinned
• Search by folder/name
• Create new workspace
• Manage workspaces

C) Workspace Creation Flow (folder + template)

Wizard steps:

1. Choose folder (existing or create new)
2. Name workspace (defaults from folder name)
3. Select template (Starter / Minimal / …)
4. Review “This will write: opencode.json, .opencode/openwork.json”

D) Workspace Settings page

Per workspace:

• rename
• change primary folder (advanced)
• view plugin config path
• list authorized folders, add/remove
• “Reset template” (re-apply template to opencode.json safely)

E) “Add Folder” affordance

When a user wants to reference a folder in a prompt (e.g. “Use files in Downloads”), provide an obvious affordance:

• “Add folder…” button near the prompt input

This triggers the same JIT folder addition flow (adds to workspace or once).

User Flows (Concrete)

Flow 1 — First run (Host)

1. User launches OpenWork.
2. Engine setup runs.
3. OpenWork lands user in dashboard with Starter Workspace active.
4. Prompt input is ready.

Flow 2 — First task (no folder selection)

1. User types: “Summarize my meeting notes.”
2. Task runs inside Starter Workspace.
3. If the task never touches external files, no folder prompts appear.

Flow 3 — Task needs local files (JIT)

1. User types: “Summarize the PDF in my Downloads.”
2. OpenWork sees access request or user clicks “Add folder…”.
3. OpenWork prompts:
   • Allow once
   • Add to workspace
   • Deny
4. If “Add to workspace”, the folder is saved in .opencode/openwork.json.

Flow 4 — Create a new workspace for a repo

1. User clicks Workspace chip → “New workspace…”.
2. Picks an existing repo folder.
3. Chooses template “Starter (recommended)”.
4. OpenWork writes opencode.json (with scheduler) and .opencode/openwork.json.
5. Workspace becomes active; Plugins/Skills tabs now reflect that folder.

Flow 5 — Switching workspaces

1. User taps Workspace chip.
2. Picks another workspace.
3. OpenWork re-connects client with directory = workspace folder.
4. UI refreshes:
   • plugin config
   • skills list
   • session list (optional filtering; future)

Technical Notes (No Implementation Yet)

• Workspace list can be stored as “recent folders” in IndexedDB, but the source of truth for workspace-scoped policy should live in the folder (.opencode/openwork.json).
• Workspace templates should be represented as a deterministic opencode.json patch.
• Starter Workspace is created/initialized on first run and pinned.

Migration

For users with existing saved projectDir and authorizedDirs:

• Treat the existing projectDir as a workspace folder.
• Create .opencode/openwork.json in that folder capturing current authorized dirs.
• Mark it as a recent workspace.

Acceptance Criteria

• Fresh install:
  • user reaches dashboard without choosing any folder
  • Starter Workspace exists and is active
  • user can run a task immediately
• User can create 2+ folder workspaces and switch between them.
• Adding access to a new folder is possible “JIT” and can be persisted to the workspace.
• Plugins and skills reflect the active folder workspace scope (project vs global).

Open Questions

• Should the Starter Workspace be fully hidden (just works) or visible and editable from day one?
• Do we want to include a minimal default opencode.json in Starter, or only prompt users to install plugins?
• How should mobile Client mode enumerate available workspaces on the host (and enforce which ones are exposed)?
• What is the cleanest OpenCode-native way to express “authorized folders” if we want to avoid any OpenWork-specific file (.opencode/openwork.json)?