headquarter/openspec/changes/archive/2026-06-12-completed-changes-archive/working-copies/proposal.md

Proposal: Workspace-Based Tool Instances

Status

Field	Value
Phase	Proposal
Based on	Explore
Next	Spec

Decisions from Explore

Decision	Value
Name	"Workspace" (supersedes existing workspace.md)
Scope	Unlimited workspaces per repository
Auto-create	No — explicit creation only
Default branch	Main/master or user-selected at creation time
Delete with running instances	Allowed with confirmation; stops and deletes all associated tool instances
Name uniqueness	Unique per project+repo (derived from project and repo names)
Deleted remote branch	On sync/update, detect and ask for confirmation to delete local workspace/branch

Problem Statement

The current tool instance creation requires users to choose between "mount" (read-only) and "clone" (writable but ephemeral) modes. This is confusing and leads to either:

• Mount mode: Tools open files read-only, frustrating editing
• Clone mode: Each instance clones the repo, wasting disk space and losing work on deletion

Proposed Solution

Introduce Workspaces as first-class entities: persistent, writable local clones of a repository that exist independently of tool instances. Users create workspaces explicitly, then start tool instances on a workspace.

Entity Relationship

Project
  └── GitRepository (canonical source)
        └── Workspace (writable clone, unlimited per repo)
              └── ToolInstance (mounts workspace path)

Key Behaviors

1. Workspace Creation: User selects a repository → picks a branch → names the workspace → clone is created on disk
2. Tool Instance Creation: User selects a workspace → picks a tool type → instance starts with workspace mounted
3. Multiple Tools per Workspace: Several tool instances can share the same workspace (e.g., terminal + code-server)
4. Persistence: Workspaces survive tool instance deletion
5. No Auto-Create: Users must explicitly create workspaces; no magic default workspace

UI Changes

• New sidebar entry: "Workspaces" (between "Projects" and "Settings")
• Workspaces page: List of all workspaces with repo/branch/status info
• Create workspace flow: Repo picker → branch picker → name input
• Start tool from workspace: Tool picker modal from workspace card
• Simplified tool creation: Remove "clone mode" / "mount mode" toggle; always use workspace

Database Changes

New table: workspaces

• id (UUID, PK)
• name (string, user-defined)
• repo_id (UUID, FK → git_repositories)
• user_id (UUID, FK → users)
• branch (string)
• path (string, absolute disk path)
• status (enum: ready, syncing, error)
• created_at, updated_at

Updated: tool_instances

• Add workspace_id (UUID, FK → workspaces, nullable for migration)
• Remove clone_mode (deprecated)
• Remove branch (moved to workspace)

File System Layout

/data/working-copies/
  └── {repo-id}/
        └── {workspace-name}/
              └── .git/
              └── [repo files]

Migration Strategy

Existing clone_mode instances:

• Extract cloned repo from instance directory
• Move to /data/working-copies/{repo-id}/{instance-name}/
• Create Workspace record
• Update instance to reference workspace
• Remove clone_mode flag

Existing mount_mode instances:

• On next start, create a workspace from the canonical repo
• Switch instance to use workspace
• Remove clone_mode flag

Out of Scope

• Auto-sync with canonical repo
• Git push/pull/branch UI
• Workspace sharing between users
• Pre-created default workspaces
• Read-only workspace mode

Risks

Risk	Mitigation
Existing users with many clone_mode instances	One-time migration on instance restart
Disk space from many workspaces	User-managed; can delete workspaces
Workspace deleted while instances are running	Allowed with confirmation; cascade-delete tool instances
Name collisions for workspace names	Unique per project+repo; derived from project and repo names

Acceptance Criteria

• User can create a workspace from any repository
• User can create unlimited workspaces per repository
• Tool instances mount the workspace path, not the canonical repo path
• Multiple tool instances can share one workspace
• Workspaces persist after tool instance deletion
• Existing clone_mode instances migrate to workspace on restart
• UI no longer shows "mount vs clone" toggle
• New sidebar navigation "Workspaces" exists

Open Questions for Spec

1. Should workspace deletion cascade-delete associated tool instances, or block? Answered: Allowed with confirmation; cascade-delete tool instances
2. Should workspace names be unique per-repo or globally unique? Answered: Unique per project+repo; derived from project and repo names
3. How do we handle the case where a workspace's branch is deleted from the remote? Answered: On sync/update, detect and ask for confirmation to delete local workspace/branch
4. Should we validate the repo path exists before creating a workspace?