# SDD Proposal: Project Pane Rework

## Status
**Phase:** proposal  
**Date:** 2026-06-16  
**Owner:** el Gentleman  

---

## User Story

As a Headquarter user, I want the Projects page to be a large list where each project entry shows its name with edit/delete actions, a horizontal list of repositories with their branches, and a vertical list of running tools per workspace, so that I can see the entire project→repo→workspace→tool hierarchy at a glance and navigate quickly.

---

## Problem Statement

The current project card uses an expandable pattern with repository cards stacked vertically. The user wants:

1. A **large list** of projects (not expandable cards).
2. Each project item has a **header** with name + Edit + Delete buttons.
3. In the content area, a **horizontal list of repositories**.
4. Each repo shows its **name** and the **branch** it was cloned from / is currently on.
5. Below each repo, a **vertical list of running tools** on that repo's workspaces.
6. Clicking a **workspace name** opens the workspace (`/workspaces/:workspaceId`).
7. Clicking a **tool name** opens the tool (web URL or terminal page).

---

## Goals

1. Replace the expandable project card with a flat list of project entries.
2. Show project actions (Edit, Delete) directly in each project header.
3. Show repositories horizontally per project.
4. Show workspaces/tools vertically under each repo, derived from live session data.
5. Make workspace and tool names clickable with correct navigation.

---

## Non-Goals

- No changes to backend APIs or data models.
- No changes to project creation/editing/deletion behavior.
- No new repo/workspace/tool actions beyond navigation.
- No mobile-specific redesign beyond responsive wrapping.

---

## Data Sources

1. **Projects + repos + workspaces**: `useProjects()` hook returns `ProjectWithRepos[]`, each with `repositories: RepositorySummary[]`, each with `workspaces: WorkspaceSummary[]`.
2. **Running tools**: `useSessions()` returns `Session[]`. Match by:
   - `session.project_id === project.id`
   - `session.repository_id === repo.id`
   - `session.workspace_name === workspace.name`
3. **Workspace ID for links**: find the workspace in `repo.workspaces` whose `name` matches `session.workspace_name`; use its `id` for `/workspaces/:workspaceId`.

---

## High-Level Approach

1. Create a new `ProjectListItem` component.
2. Render it inside a `.project-list` container in `ProjectsPage.tsx`.
3. For each project:
   - Header: name + Edit + Delete.
   - Body: horizontal scroll/flex row of `.repo-item` cards.
4. For each repo:
   - Show repo name + branch label.
   - Show vertical list of workspaces with running tools.
5. For each workspace under the repo:
   - Show workspace name (link to `/workspaces/:id`).
   - Show running tool names/icons (link to tool URL or terminal).
6. Remove the old `ProjectCard` usage from desktop view (keep it for mobile detail view if still needed).
7. Add CSS for the new layout in `styles/pages/projects.css`.

---

## Risks

| Risk | Severity | Mitigation |
|------|----------|------------|
| Workspace name match may be ambiguous | Medium | Use workspace ID when available; fall back to name match with a warning. |
| Many sessions make list noisy | Medium | Only show running sessions; group by workspace. |
| Horizontal repo list overflows on small screens | Low | Use flex-wrap and min-width; scroll on very small screens. |

---

## Effort Estimate

| Area | Files | Lines (est) |
|---|---|---|
| New component | 1 | ~180 |
| ProjectsPage integration | 1 | ~60 |
| CSS | 1 | ~120 |
| OpenSpec | 3 | ~80 |
| **Total** | **6** | **~440** |

Slightly above 400-line budget; may need to split into component + page/CSS PRs.

---

## Next Recommended Phase

**Spec** — detail component props, exact markup, CSS classes, and navigation logic.

Should I proceed to spec?