headquarter/openspec/proposals/project-pane-rework.md

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?