headquarter/openspec/changes/workspace-visual-overhaul/specs/spec.md

Workspace Visual Overhaul Specification

Requirements

Functional Requirements

1. Header Actions: All primary project actions in workspace header (right-aligned)
2. Project Settings Page: Dedicated settings page with tabs
3. Repository Management in Settings: Move repo management to settings tab
4. Sidebar Simplification: Remove management links from sidebar
5. Consistent Navigation: Follow GitHub-style patterns

Non-Functional Requirements

1. Responsive: Works on desktop, tablet, and mobile
2. Accessible: Keyboard navigation, screen reader support
3. Performant: No layout shifts, smooth transitions
4. Maintainable: Clean component separation

UI Specification

Workspace Header

Left Side:

• Project icon (📁 or custom)
• Project name (bold, 1.25rem)
• Optional: Current repository name (smaller, muted)

Right Side (Actions):

• "History" button (clock icon) → navigates to history
• "Settings" button (gear icon) → navigates to settings

States:

• Loading: Show skeleton or spinner
• Error: Show error message with retry

Project Settings Page

Layout:

• Two-column layout (sidebar tabs + content)
• Mobile: Tabs at top, content below

Tabs:

General Tab

• Project name input (required)
• Description textarea (optional)
• Created at (read-only)
• Updated at (read-only)
• Save changes button
• Cancel button (if dirty)

Repositories Tab

• Repository list (same as current repo management)
• Add repository button
• Each repo card:
  • Name
  • Remote URL (truncated)
  • Last updated
  • Actions: Delete

Members Tab (Placeholder)

• "Coming soon" message
• Brief description of future feature

Danger Zone

• Red background/warning styling
• Delete project button
• Confirmation dialog on click

Sidebar Changes

Current sidebar items:

• Branch selector
• File tree
• Manage Repositories link

New sidebar items:

• Branch selector (keep)
• File tree (keep)
• Manage Repositories (remove)

Route Changes

Remove Routes

• /projects/:projectId/repositories → Moved to settings

New Routes

• /projects/:projectId/settings → Settings (defaults to General tab)
• /projects/:projectId/settings/general → General settings
• /projects/:projectId/settings/repositories → Repository management
• /projects/:projectId/settings/members → Members (placeholder)

Keep Routes

• /projects → Project list
• /projects/:projectId → Workspace
• /projects/:projectId/repositories/:repoId/history → History

Component Specification

WorkspaceHeader

interface WorkspaceHeaderProps {
  project: {
    id: string;
    name: string;
    description?: string;
  };
  currentRepo?: {
    id: string;
    name: string;
  };
  onNavigateToHistory: () => void;
  onNavigateToSettings: () => void;
}

ProjectSettingsPage

interface ProjectSettingsProps {
  projectId: string;
}

// Tabs configuration
const TABS = [
  { id: 'general', label: 'General', icon: 'settings' },
  { id: 'repositories', label: 'Repositories', icon: 'repo' },
  { id: 'members', label: 'Members', icon: 'people' },
];

SettingsTabLayout

interface SettingsTabLayoutProps {
  projectId: string;
  activeTab: string;
  children: React.ReactNode;
}

API Requirements

PUT /projects/:id

Update project details.

Request Body:

{
  "name": "Updated Project Name",
  "description": "Updated description"
}

Response 200:

{
  "id": "uuid",
  "name": "Updated Project Name",
  "description": "Updated description",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-02T00:00:00Z"
}

Error Handling

• Project not found: Show 404 page
• Permission denied: Show auth error, redirect to login
• Save failed: Show toast notification, keep form state
• Delete failed: Show error in danger zone

Testing Strategy

Frontend Tests

• Test header navigation (History, Settings buttons)
• Test settings tabs switching
• Test form validation (name required)
• Test delete confirmation flow
• Test responsive layout

Integration Tests

• Test navigation flow: workspace → settings → back
• Test route changes
• Test data persistence (save project changes)