Skip to content

The open-source app everyone uses to manage agents at work

Expand workspace plan for migration and cloud execution

Dotta752a53e38e25
diff --git a/doc/plans/workspace-product-model-and-work-product.md b/doc/plans/workspace-product-model-and-work-product.md
index 3b201e7d11..ae5b8e793d 100644
--- a/doc/plans/workspace-product-model-and-work-product.md
+++ b/doc/plans/workspace-product-model-and-work-product.md
@@ -38,6 +38,8 @@ The main product risk is overloading one concept to do too much:
- commits
- documents and artifacts
5. Keep the main navigation and task board simple.
+6. Seamlessly upgrade existing Paperclip users to the new model without forcing disruptive reconfiguration.
+7. Support cloud-hosted Paperclip deployments where execution happens in remote or adapter-managed environments rather than local workers.
## Non-Goals
@@ -45,6 +47,7 @@ The main product risk is overloading one concept to do too much:
- Requiring every issue to have its own branch or PR
- Requiring every project to configure code/workspace automation
- Making workspaces a top-level global navigation primitive in V1
+- Requiring a local filesystem path or local git checkout to use workspace-aware execution
## Core Product Decisions
@@ -86,6 +89,7 @@ Examples:
- an isolated git worktree
- a long-lived operator branch checkout
- an adapter-managed remote sandbox
+- a cloud agent provider's isolated branch/session environment
This object must be recorded explicitly so that Paperclip can:
@@ -107,7 +111,38 @@ Paperclip should treat PRs as a type of work product linked back to:
Git-specific automation should live under workspace policy, not under the core issue abstraction.
-### 5. Subissues remain planning and ownership structure
+### 5. Existing users must upgrade automatically
+
+Paperclip already has users and existing project/task data. Any new model must preserve continuity.
+
+The product should default existing installs into a sensible compatibility mode:
+
+- existing projects without workspace configuration continue to work unchanged
+- existing `project_workspaces` become the durable `project workspace` objects
+- existing project execution workspace policy is mapped forward rather than discarded
+- issues without explicit workspace fields continue to inherit current behavior
+
+This migration should feel additive, not like a mandatory re-onboarding flow.
+
+### 6. Cloud-hosted Paperclip must be a first-class deployment mode
+
+Paperclip cannot assume that it is running on the same machine as the code.
+
+In cloud deployments, Paperclip may:
+
+- run on Vercel or another serverless host
+- have no long-lived local worker process
+- delegate execution to a remote coding agent or provider-managed sandbox
+- receive back a branch, PR, preview URL, or artifact from that remote environment
+
+The model therefore must be portable:
+
+- `project workspace` may be remote-managed, not local
+- `execution workspace` may have no local `cwd`
+- `runtime services` may be tracked by provider reference and URL rather than a host process
+- work product harvesting must handle externally owned previews and PRs
+
+### 7. Subissues remain planning and ownership structure
Subissues are for decomposition and parallel ownership.
@@ -131,6 +166,11 @@ Use these terms consistently in product copy:
- `Work product`: previews, PRs, branches, commits, artifacts, docs
- `Runtime service`: a process or service Paperclip owns or tracks for a workspace
+Use these terms consistently in migration and deployment messaging:
+
+- `Compatible mode`: existing behavior preserved without new workspace automation
+- `Adapter-managed workspace`: workspace realized by a remote or cloud execution provider
+
Avoid teaching users that "workspace" always means "git worktree on my machine".
## Product Object Model
@@ -176,6 +216,7 @@ from:
- "what temporary execution environment did this issue run in?"
That keeps the model simple for solo users while still supporting advanced automation.
+It also lets cloud-hosted Paperclip deployments point at codebases and remotes without pretending the Paperclip host has direct filesystem access.
### Proposed fields
@@ -206,6 +247,7 @@ That keeps the model simple for solo users while still supporting advanced autom
- `sourceType=non_git_path` is important so non-git projects are first-class.
- `setupCommand` and `cleanupCommand` should be allowed here for workspace-root bootstrap, even when isolated execution is not used.
- For a monorepo, multiple project workspaces may point at different roots or packages under one repo.
+- `sourceType=remote_managed` is important for cloud deployments where the durable codebase is defined by provider/repo metadata rather than a local checkout path.
## 3. Project Execution Workspace Policy
@@ -220,6 +262,7 @@ This lets Paperclip support:
- direct editing in a shared workspace
- isolated workspaces for issue parallelism
- long-lived integration branch workflows
+- remote cloud-agent execution that returns a branch or PR
without forcing every issue or agent to expose low-level runtime configuration.
@@ -305,6 +348,7 @@ Examples:
- if the project has no workspace automation, these fields may all be null
- if the project has one primary workspace, issue creation should default to it silently
- `reuse_existing` is advanced-only and should target active execution workspaces, not the whole workspace universe
+- existing issues without these fields should behave as `inherit` during migration
## 5. Execution Workspace
@@ -321,6 +365,7 @@ Without an explicit `execution workspace` record, Paperclip has nowhere stable t
- PR linkage
- cleanup state
- "reuse this existing integration branch" behavior
+- remote provider session identity
### Proposed new object
@@ -354,6 +399,11 @@ Without an explicit `execution workspace` record, Paperclip has nowhere stable t
- `baseRef`
- `branchName`
- `providerRef`
+- `providerType`
+ - `local_fs`
+ - `git_worktree`
+ - `adapter_managed`
+ - `cloud_sandbox`
- `derivedFromExecutionWorkspaceId`
- `lastUsedAt`
- `openedAt`
@@ -368,6 +418,7 @@ Without an explicit `execution workspace` record, Paperclip has nowhere stable t
- `sourceIssueId` is the issue that originally caused the workspace to be created, not necessarily the only issue linked to it later.
- multiple issues may link to the same execution workspace in a long-lived branch workflow.
+- `cwd` may be null for remote execution workspaces; provider identity and work product links still make the object useful.
## 6. Issue-to-Execution Workspace Link
@@ -473,6 +524,7 @@ without turning issues into a raw dump of adapter details.
- previews are stored here as `type=preview_url` or `runtime_service`
- Paperclip-owned processes should update health/status automatically
- external providers should at least store link, provider, external id, and latest known state
+- cloud agents should be able to create work product records without Paperclip owning the execution host
## Page and UI Model
@@ -550,6 +602,7 @@ Card/list columns:
- active execution workspaces count
- active issue count
- active preview count
+- hosting type / provider when remote-managed
Actions:
@@ -586,6 +639,7 @@ Fields:
- `Derived workspace parent directory`
Hide git-specific fields when the selected workspace is not git-backed.
+Hide local-path-specific fields when the selected workspace is remote-managed.
#### Section: `Pull Requests`
@@ -637,6 +691,8 @@ Entry point: `Project > Code > Add workspace`
- `Remote managed`
- `Local path`
- `Repository URL`
+- `Remote provider`
+- `Remote workspace reference`
- `Default ref`
- `Set as default workspace`
- `Setup command`
@@ -646,6 +702,7 @@ Entry point: `Project > Code > Add workspace`
- if source type is non-git, hide branch/PR-specific setup
- if source type is git, show ref and optional advanced branch fields
+- if source type is remote-managed, show provider/reference fields and hide local-path-only configuration
- for simple solo users, this can be one path field and one save button
## 4. Issue Create Flow
@@ -695,6 +752,10 @@ not:
- choose from a long mixed list of roots, derived worktrees, previews, and branch names
+### Migration rule
+
+For existing users, issue creation should continue to look the same until a project explicitly enables richer workspace behavior.
+
## 5. Issue Detail
Issue detail should expose workspace and work product clearly, but without becoming a code host UI.
@@ -790,6 +851,7 @@ It does not need to be in the main sidebar.
- source issue
- linked issues
- branch/ref
+- provider/session identity
- active runtime services
- previews
- PRs
@@ -812,6 +874,7 @@ Inbox should surface actionable work product events, not every implementation de
- preview unhealthy
- workspace cleanup failed
- runtime service failed
+- remote cloud-agent run returned PR or preview that needs review
### Do not show by default
@@ -853,6 +916,101 @@ For issues with linked work product, show compact badges:
- `Workspace mode`
- `Codebase`
+## Upgrade and Migration Plan
+
+## 1. Product-level migration stance
+
+Migration must be silent-by-default and compatibility-preserving.
+
+Existing users should not be forced to:
+
+- create new workspace objects by hand before they can keep working
+- re-tag old issues
+- learn new workspace concepts before basic issue flows continue to function
+
+## 2. Existing project migration
+
+On upgrade:
+
+- existing `project_workspaces` records are retained and shown as `Project Workspaces`
+- the current primary workspace remains the default codebase
+- existing project execution workspace policy is mapped into the new `Project Execution Workspace Policy` surface
+- projects with no execution workspace policy stay in compatible/shared mode
+
+## 3. Existing issue migration
+
+On upgrade:
+
+- existing issues default to `executionWorkspacePreference=inherit`
+- if an issue already has execution workspace settings, map them forward directly
+- if an issue has no explicit workspace data, preserve existing behavior and do not force a user-visible choice
+
+## 4. Existing run/runtime migration
+
+On upgrade:
+
+- active or recent runtime services can be backfilled into execution workspace history where feasible
+- missing history should not block rollout; forward correctness matters more than perfect historical reconstruction
+
+## 5. Rollout UX
+
+Use additive language in the UI:
+
+- `Code`
+- `Workspace automation`
+- `Optional`
+- `Advanced`
+
+Avoid migration copy that implies users were previously using the product "wrong".
+
+## Cloud Deployment Requirements
+
+## 1. Paperclip host and execution host must be decoupled
+
+Paperclip may run:
+
+- locally with direct filesystem access
+- in a cloud app host such as Vercel
+- in a hybrid setup with external job runners
+
+The workspace model must work in all three.
+
+## 2. Remote execution must support first-class work product reporting
+
+A cloud agent should be able to:
+
+- resolve a project workspace
+- realize an adapter-managed execution workspace remotely
+- produce a branch
+- open or update a PR
+- emit preview URLs
+- register artifacts
+
+without the Paperclip host itself running local git or local preview processes.
+
+## 3. Local-only assumptions must be optional
+
+The following must be optional, not required:
+
+- local `cwd`
+- local git CLI
+- host-managed worktree directories
+- host-owned long-lived preview processes
+
+## 4. Same product surface, different provider behavior
+
+The UI should not split into "local mode" and "cloud mode" products.
+
+Instead:
+
+- local projects show path/git implementation details
+- cloud projects show provider/reference details
+- both surface the same high-level objects:
+ - project workspace
+ - execution workspace
+ - work product
+ - runtime service or preview
+
## Behavior Rules
## 1. Cleanup must not depend on agents remembering `in_review`
@@ -921,6 +1079,7 @@ That keeps Paperclip focused on coordination and visibility instead of splitting
1. Add `execution_workspaces`
2. Link runs, issues, previews, and PRs to it
3. Add simple execution workspace detail page
+4. Make `cwd` optional and ensure provider-managed remote workspaces are supported from day one
## Phase 3: Add work product model
@@ -928,6 +1087,7 @@ That keeps Paperclip focused on coordination and visibility instead of splitting
2. Ingest PRs, previews, branches, commits
3. Add issue `Work Product` tab
4. Add inbox items for actionable work product state changes
+5. Support remote agent-created PR/preview reporting without local ownership
## Phase 4: Add advanced reuse and cleanup workflows
@@ -935,6 +1095,7 @@ That keeps Paperclip focused on coordination and visibility instead of splitting
2. Add cleanup lifecycle UI
3. Add operator branch workflow shortcuts
4. Add richer external preview harvesting
+5. Add migration tooling/backfill where it improves continuity for existing users
## Why This Model Is Right
@@ -953,6 +1114,12 @@ Most importantly, it keeps the abstractions clean:
- work product defines what came out of the work
- PRs remain outputs, not the core task model
+It also keeps the rollout practical:
+
+- existing users can upgrade without workflow breakage
+- local-first installs stay simple
+- cloud-hosted Paperclip deployments remain first-class
+
That is a better fit for Paperclip than either extreme:
- hiding workspace behavior until nobody understands it