headquarter/openspec/changes/archive/2026-06-12-completed-changes-archive/workspace-first-ui/proposal.md

Proposal: Workspace-First UI Refresh

Status

Field	Value
Phase	Proposal
Based on	Working Copies Spec
Next	Spec

Problem

The current UI has two competing "workspace" concepts:

1. Old "Repository Workspace" (repo-workspace.tsx): A file browser + editor + git toolbar view tied to a repository. This was the default view when opening a project. It reads files from the repo path directly and offers quick editing.
2. New "Workspace" (workspaces.tsx): A list of persistent writable clones that tool instances mount. These are first-class entities with their own lifecycle.

These two concepts confuse users. The old workspace is redundant now that workspaces are persistent clones — users should work inside a workspace, not directly on the repo.

Additionally:

• The Projects page only shows a list of projects with "Open Workspace" links — no visibility into repos or workspaces
• Tool instances are spawned from the repo-workspace view, not from the workspace view
• Mobile layout of the old workspace is cramped and not well-suited for the new paradigm

Solution

Replace the old "Repository Workspace" with a Workspace-First navigation model:

New Information Architecture

Projects
  └── Project Card (inline repos + workspaces)
        └── Repo: "my-app"
              ├── Workspace: "main" → /workspaces/{id}
              ├── Workspace: "feature-auth" → /workspaces/{id}
              └── [+ New Workspace]
Workspaces
  └── All Workspaces (grid/list)
        └── Workspace Card → /workspaces/{id}

Workspace Detail Page (/workspaces/:workspaceId)

The workspace detail page is the primary work surface. It replaces the old repo-workspace:

┌──────────────────────────────────────────────────────────────┐
│  {project} / {repo} / {workspace-name}     [Start Tool ▼]   │
├──────────────┬───────────────────────────────────────────────┤
│              │  Tabs: [Files] [Git] [Tools]                  │
│  File Tree   ├───────────────────────────────────────────────┤
│  (workspace  │                                               │
│   clone)     │  {active tab content}                         │
│              │                                               │
│  📁 src/     │                                               │
│  📄 README   │                                               │
│              │                                               │
├──────────────┤                                               │
│  Git Status  │                                               │
│  (compact)   │                                               │
└──────────────┴───────────────────────────────────────────────┘

Panels (collapsible, IDE-style):

• Files: File tree from workspace clone path + file viewer/editor
• Git: Commit panel, branch selector, push/pull/fetch actions (operating on workspace clone)
• Tools: List of active tool instances on this workspace + spawn new tool

Start Tool: Inline modal (not page navigation) to spawn a tool instance on this workspace.

Projects Page Refresh

Project cards now show:

• Project name + description
• Repositories (accordion/list)
• For each repo: its workspaces as clickable chips/cards
• "New Workspace" button per repo

┌─────────────────────────────────────────────┐
│ My Project                                  │
│ A web application                            │
├─────────────────────────────────────────────┤
│ Repositories:                               │
│                                             │
│ ▼ my-app (git@github.com:...)               │
│   ┌─────────┐ ┌─────────────┐ [+ New]      │
│   │ main    │ │ feature-auth│               │
│   │ ● 2     │ │ ● 0         │               │
│   └─────────┘ └─────────────┘               │
│                                             │
│ ▶ api-service                               │
│   ┌─────────┐ [+ New]                      │
│   │ main    │                               │
│   └─────────┘                               │
└─────────────────────────────────────────────┘

Mobile Layout

Bottom tab bar (4 tabs):

• Files: Full-screen file tree + viewer
• Git: Compact commit panel + action buttons
• Tools: Instance list + spawn button
• Menu: Workspace switcher, settings

Swipe between tabs. File tree is always accessible.

Deleted

• pages/repo-workspace.tsx — old repository workspace (file browser + editor on repo path)
• Route /projects/:projectId → now shows project detail, not file browser
• Old workspace header component
• Git toolbar component (replaced by panel in workspace detail)

Scope

In Scope

• New workspace detail page (/workspaces/:workspaceId)
• File browser reading from workspace clone path
• File viewer/editor for workspace files
• Git operations on workspace clone (status, commit, push, pull, fetch, branch)
• Tool instance list per workspace
• Inline tool spawn modal
• Collapsible IDE-style panels (desktop)
• Bottom tab bar layout (mobile)
• Projects page refresh (inline repos + workspaces)
• Workspace list page improvements (link to detail page)
• Backend: file endpoints for workspace path
• Backend: git endpoints for workspace path
• Delete old repo-workspace.tsx and related components
• Update routing

Out of Scope

• Git history / diff view (deferred, can reuse existing page)
• Workspace sharing between users
• Advanced IDE features (search, multi-file edit)
• Auto-sync on schedule
• Terminal integration inside workspace page

Decisions

#	Question	Answer
1	Projects page → what happens on "Open"?	A — Show project detail with repos + workspaces inline
2	Workspace page layout?	C — Collapsible panels, IDE-style
3	File browser source?	Workspace clone path (/data/working-copies/{repo-id}/{name}/)
4	Git actions scope?	Workspace clone
5	Tool spawning?	Inline modal on workspace page
6	Mobile layout?	Bottom tab bar (Files / Git / Tools / Menu), swipeable
7	Old workspace fallback?	No fallback — delete immediately
8	Projects page detail level?	Inline workspace cards on project page

Open Questions for Spec

1. Should the workspace detail page URL be /workspaces/:id or nested under project/repo?
2. Should we keep the sidebar Workspaces nav entry, or rely on Projects → Workspace flow?
3. How does "New Workspace" flow work from Projects page — inline form or navigate to create page?
4. Should workspace detail show repo remote URL and allow switching branches?
5. What happens when a workspace has no tool instances yet — show empty state or prompt to spawn?

Risks

Risk	Mitigation
Users confused by navigation change	Keep "Workspaces" in sidebar, add breadcrumbs
Large frontend refactor	Break into 3 PRs: backend endpoints, workspace detail page, projects refresh
Mobile layout complexity	Prototype with CSS grid first, test on actual device
Git operations on workspace path	Reuse existing git service, just change the path argument

Success Criteria

• Old repo-workspace.tsx is deleted
• /projects/:id shows project detail with repos and workspaces
• /workspaces/:id shows workspace detail with Files, Git, Tools panels
• File browser reads from workspace clone path
• Git commit/push/pull work on workspace clone
• Tool spawn modal creates instance with workspace mounted
• Mobile layout uses bottom tabs
• All existing tests pass (or updated)
• ruff clean, TypeScript clean, eslint clean