headquarter/openspec/changes/working-copies/tasks.md

# Tasks: Workspace-Based Tool Instances

## Status

| Field | Value |
|---|---|
| Phase | **Tasks** |
| Based on | [Design](design.md) |
| Next | Apply |

## PR Breakdown

### PR-1: Backend Foundation
**Scope**: Database migration, models, services, API endpoints for workspaces
**Est. lines**: ~800 backend, ~300 tests
**Files touched**: 8 new, 2 modified

**Tasks**:
1. [x] Create Alembic migration for `workspaces` table + `workspace_id` on `tool_instances`
2. [x] Create `Workspace` model (`apps/api/src/models/workspace.py`)
3. [x] Add `workspace_id` to `ToolInstance` model (nullable FK)
4. [x] Create `GitService` (`apps/api/src/services/git_service.py`) — clone, fetch, pull, branch_exists_remotely
5. [x] Create `WorkspaceManager` (`apps/api/src/services/workspace_manager.py`) — create, delete, sync
6. [x] Create workspace API router (`apps/api/src/api/workspaces.py`) — CRUD + sync endpoints
7. [x] Add workspace routes to FastAPI app (`apps/api/src/main.py`)
8. [ ] Write unit tests for GitService
9. [ ] Write integration tests for workspace CRUD
10. [ ] Write integration tests for delete-with-instances (409 behavior)
11. [ ] Write integration tests for sync-with-deleted-branch (409 behavior)

### PR-2: Backend Integration
**Scope**: Tool instance creation/start uses workspace instead of repo path
**Est. lines**: ~400 backend, ~200 tests
**Files touched**: 3 modified

**Tasks**:
1. [x] Update `create_instance` endpoint to accept `workspace_id` instead of `clone_mode`
2. [x] Update `start_instance` to mount workspace path (`workspace.path`) instead of repo path
3. [x] Update compose generation to use `WORKSPACE_PATH` variable
4. [x] Update `tool_instances.py` compose template rendering
5. [ ] Write integration tests for instance creation with workspace
6. [ ] Write integration tests for instance start with workspace mount
7. [x] Verify old mount_mode instances still work (backward compat)

### PR-3: Frontend Core
**Scope**: Workspaces UI — list, create, card, actions
**Est. lines**: ~1,200 frontend, ~400 tests
**Files touched**: 10 new, 2 modified

**Tasks**:
1. [x] Create workspace types (`apps/web/src/types/workspace.ts`)
2. [x] Create workspace API client (`apps/web/src/api/workspaces.ts`)
3. [x] Create `useWorkspaces` hook (`apps/web/src/hooks/use-workspaces.ts`)
4. [x] Create `useWorkspaceActions` hook (`apps/web/src/hooks/use-workspace-actions.ts`)
5. [x] Create `WorkspaceCard` component (`apps/web/src/components/workspace-card.tsx`)
6. [x] Create `WorkspaceCreateForm` component (`apps/web/src/components/workspace-create-form.tsx`)
7. [x] Create `StartToolModal` component (`apps/web/src/components/start-tool-modal.tsx`)
8. [ ] Create `WorkspacesPage` (`apps/web/src/pages/workspaces.tsx`)
9. [ ] Update `Sidebar` to add Workspaces nav item
10. [ ] Update router/routes to include `/workspaces`
11. [ ] Write component tests for WorkspaceCard
12. [ ] Write hook tests for useWorkspaceActions
13. [ ] Write tests for create form validation

### PR-4: Frontend Integration
**Scope**: Update existing flows to use workspaces, dashboard integration
**Est. lines**: ~600 frontend, ~200 tests
**Files touched**: 5 modified

**Tasks**:
1. [x] Update `CreateSessionForm` to use workspace picker instead of repo+clone_mode
2. [ ] Update `SessionsPage` dashboard to show workspaces section
3. [x] Update `SessionCard` to show workspace name instead of clone mode
4. [x] Update `useInstanceActions` to pass `workspace_id` on create
5. [x] Remove clone_mode/mount_mode UI toggles
6. [x] Update types to remove deprecated `clone_mode` field
7. [ ] Write integration tests for full create-workspace → start-tool flow
8. [ ] Write tests for dashboard workspaces section

## Acceptance Criteria (All PRs)

- [x] User can create a workspace from any repository
- [x] User can create unlimited workspaces per repository
- [x] Workspace names are unique per repo
- [x] Tool instances mount the workspace path
- [x] Multiple tool instances can share one workspace
- [x] Workspaces persist after tool instance deletion
- [x] Deleting a workspace with running instances shows confirmation, stops and deletes instances
- [x] Syncing a workspace with a deleted remote branch shows confirmation
- [x] UI no longer shows "mount vs clone" toggle
- [ ] New sidebar navigation "Workspaces" exists
- [x] All existing tests still pass
- [x] ruff clean
- [x] TypeScript compilation clean

## Implementation Order

```
PR-1 (Backend Foundation)
  → PR-2 (Backend Integration)
    → PR-3 (Frontend Core)
      → PR-4 (Frontend Integration)
```

Each PR depends on the previous. No parallel work.

## Verification Steps per PR

### PR-1
```bash
cd apps/api
alembic upgrade head
pytest tests/unit/test_git_service.py tests/integration/test_workspaces.py -v
python -m ruff check src/services/git_service.py src/services/workspace_manager.py src/api/workspaces.py
```

### PR-2
```bash
cd apps/api
pytest tests/integration/test_tool_instances_with_workspace.py -v
python -m ruff check src/api/tool_instances.py
```

### PR-3
```bash
cd apps/web
npm run test -- --run workspaces
npx tsc --noEmit
npx eslint src/pages/workspaces.tsx src/components/workspace-*.tsx
```

### PR-4
```bash
cd apps/web
npm run test -- --run sessions create-session
npx tsc --noEmit
npx eslint src/pages/sessions.tsx src/components/create-session-form.tsx
```