headquarter/openspec/changes/workspace-first-ui/tasks.md

Tasks: Workspace-First UI Refresh

Status

Field	Value
Phase	Tasks
Based on	Design
Next	Apply

PR Breakdown

PR-1: Backend — Workspace File, Git & Instance Endpoints

Scope: All new backend endpoints for workspace-scoped operations Est. lines: ~900 backend, ~400 tests Files touched: 10 new, 3 modified

Tasks:

1. Create FileService (apps/api/src/services/file_service.py)
2. Create GitOperations service (apps/api/src/services/git_operations.py)
3. Create workspace_files API router (apps/api/src/api/workspace_files.py)
4. Create workspace_git API router (apps/api/src/api/workspace_git.py)
5. Create workspace_instances API router (apps/api/src/api/workspace_instances.py)
6. Register new routers in main.py
7. Update workspaces.py POST to accept repo_id directly
8. Enrich projects.py list response with repos + workspaces
9. Write unit tests for FileService
10. Write unit tests for GitOperations
11. Write integration tests for workspace file endpoints
12. Write integration tests for workspace git endpoints
13. Write integration tests for workspace instance endpoints

PR-2: Frontend — Workspace Detail Page

Scope: Workspace detail page with 4 tabs, replaces old repo-workspace Est. lines: ~1,400 frontend, ~300 tests Files touched: 14 new, 3 modified

Tasks:

1. Create useWorkspaceFiles hook
2. Create useWorkspaceGit hook
3. Create useWorkspaceInstances hook
4. Create workspace API clients (workspace-files.ts, workspace-git.ts, workspace-instances.ts)
5. Create WorkspaceHeader component
6. Create WorkspaceTabs component
7. Create WorkspaceFilePanel component (file tree + viewer + git toolbar)
8. Create GitToolbar component (collapsible)
9. Create WorkspaceGitPanel component (history + diff)
10. Create WorkspaceToolsPanel component (instances + spawn modal)
11. Create WorkspaceSettingsPanel component
12. Create WorkspaceDetailPage page
13. Add /workspaces/:id route
14. Delete repo-workspace.tsx and related components
15. Write component tests for WorkspaceFilePanel
16. Write component tests for GitToolbar
17. Write component tests for WorkspaceToolsPanel

PR-3: Frontend — Projects Page Refresh & Routing

Scope: Projects page with inline repos + workspaces, mobile layout Est. lines: ~800 frontend, ~200 tests Files touched: 5 new, 5 modified

Tasks:

1. Update projects.ts API client for enriched response
2. Create useProjectsEnriched hook
3. Create ProjectCard component
4. Create RepoSection component
5. Create WorkspaceChip component
6. Create NewWorkspaceInline component
7. Rewrite ProjectsPage
8. Create ProjectDetailPage (or inline detail on ProjectsPage)
9. Update AppShell nav order (Workspaces → Projects)
10. Update WorkspacesPage to link to detail
11. Add mobile tab bar to workspace detail
12. Update router: /projects/:id → project detail, remove old repo-workspace
13. Write component tests for ProjectCard
14. Write component tests for RepoSection
15. Write tests for NewWorkspaceInline

Acceptance Criteria (All PRs)

• Old repo-workspace.tsx is deleted
• /projects/:id shows project detail with repos + workspaces
• /workspaces/:id shows workspace detail with 4 tabs
• File browser reads from workspace clone path
• File viewer/editor works on workspace files
• Git toolbar on Files tab supports commit/push/pull/fetch
• Git tab shows commit history
• Tools tab lists instances + spawn modal (or empty prompt)
• Settings tab shows workspace info + rename/sync/delete
• Projects page shows inline repos + workspace cards
• Inline "New Workspace" form on project page
• Mobile: 4-tab bottom navigation
• All existing tests pass or updated
• ruff clean
• TypeScript compilation clean
• eslint clean

Implementation Order

PR-1 (Backend endpoints)
  → PR-2 (Workspace detail page)
    → PR-3 (Projects refresh + routing)

Each PR depends on the previous. No parallel work.

Verification Steps per PR

PR-1

cd apps/api
pytest tests/unit/test_file_service.py tests/unit/test_git_operations.py -v
pytest tests/integration/test_workspace_files.py tests/integration/test_workspace_git.py tests/integration/test_workspace_instances.py -v
python -m ruff check src/services/file_service.py src/services/git_operations.py src/api/workspace_*.py

PR-2

cd apps/web
npx tsc --noEmit
npx eslint src/pages/workspace-detail.tsx src/components/workspace/
npm run test -- --run workspace-detail

PR-3

cd apps/web
npx tsc --noEmit
npx eslint src/pages/projects.tsx src/components/project/
npm run test -- --run projects