Developer
8c1948d226
Move the following completed changes from openspec/changes/ to openspec/changes/archive/2026-06-12-completed-changes-archive/: - multi-session-terminal-ux - reorganize-long-files - working-copies - workspace-first-ui Update parent and archive .pi-map*.md indexes to reflect the move and remove the transient active-changes-archive grouping. openspec/changes/ now contains only the archive/ directory.
185 lines
8.7 KiB
Markdown
185 lines
8.7 KiB
Markdown
# Proposal: Workspace-First UI Refresh
|
|
|
|
## Status
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Phase | **Proposal** |
|
|
| Based on | [Working Copies Spec](../working-copies/spec.md) |
|
|
| 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
|