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 (inline in WorkspaceDetailPage)
6. Create WorkspaceTabs component (inline in WorkspaceDetailPage)
7. Create WorkspaceFilePanel component (inline in WorkspaceDetailPage)
8. Create GitToolbar component (inline in Files tab)
9. Create WorkspaceGitPanel component (inline in WorkspaceDetailPage)
10. Create WorkspaceToolsPanel component (inline in WorkspaceDetailPage)
11. Create WorkspaceSettingsPanel component (inline in WorkspaceDetailPage)
12. Create WorkspaceDetailPage page
13. Add /workspaces/:id route
14. Delete repo-workspace.tsx and related components
15. Write component tests for WorkspaceDetailPage

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 useProjects hook with enriched response
3. Create ProjectCard component
4. Inline repo section in ProjectCard
5. Inline workspace chips in ProjectCard
6. Inline new workspace form in ProjectCard
7. Rewrite ProjectsPage
8. Inline project detail on ProjectsPage (mobile + desktop)
9. Update AppShell nav order (Workspaces → Projects)
10. Update WorkspacesPage / WorkspaceCard to link to detail
11. Add mobile tab bar to workspace detail
12. Remove old repo-workspace route and components
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 (inline on ProjectsPage)
• /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 (ruff not available in current environment; py_compile passed)
• 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