[Phase 3] Workspace View - Overview & Initialization

[frankbria]

Overview

Implement the Workspace View - the home/landing page that shows workspace state and provides quick access to the golden path workflow.

Reference: docs/PHASE_3_UI_ARCHITECTURE.md Section 1.1, 3.1

Purpose

Initialize and overview the current workspace state.

User Actions

• Initialize workspace (one-time setup per repo)
• View workspace metadata (tech stack, git status)
• Quick access to PRD, tasks, and active runs

Components

WorkspaceView
├── WorkspaceHeader
│   ├── RepoPathDisplay
│   └── InitializeWorkspaceButton (if not initialized)
├── WorkspaceStatsCards
│   ├── TechStackCard
│   ├── TaskStatsCard (READY, IN_PROGRESS, DONE counts)
│   └── ActiveRunsCard
└── RecentActivityFeed
    └── ActivityItem[] (event type, timestamp, description)

API Endpoints Used

• GET /api/v2/workspace/status - Workspace status
• POST /api/v2/workspace/init - Initialize workspace
• GET /api/v2/tasks - Task counts by status

Acceptance Criteria

• Shows "Initialize Workspace" button if workspace not initialized
• Displays repo path and tech stack after initialization
• Shows task counts grouped by status (READY, IN_PROGRESS, DONE, BLOCKED, FAILED)
• Shows count of active runs
• Recent activity feed shows last 5 events
• Quick navigation links to PRD, Tasks views
• Responsive layout using Shadcn/UI components
• Uses Hugeicons for all icons

Route

/ (home)

Real-time Requirements

None - static view, refresh on navigation

[traycerai]

Plan

Observations

The codebase has a legacy project-based architecture at the root route (/) showing a ProjectList component. Phase 3 introduces a workspace-based architecture using v2 API endpoints (/api/v2/workspaces, /api/v2/tasks). The frontend uses Next.js 14 App Router, Shadcn/UI Nova template, Hugeicons, and SWR for data fetching. The backend workspace API is implemented in file:codeframe/ui/routers/workspace_v2.py and tasks API in file:codeframe/ui/routers/tasks_v2.py. The Phase 3 architecture document defines a complete golden path UI with 6 core views. A brand new UI structure is required, separate from the legacy pages, to implement the Phase 3 vision.

Approach

Create a brand new UI application structure alongside the legacy codebase. Establish a new Next.js app directory at web-ui/ with a fresh component architecture following the Phase 3 specification. Build the Workspace View as the first Phase 3 view, implementing the component hierarchy: WorkspaceView → WorkspaceHeader, WorkspaceStatsCards, RecentActivityFeed. Use Shadcn/UI components (Card, Button, Badge) and Hugeicons for consistency with the Nova template. Implement workspace initialization flow with conditional rendering based on workspace existence. Fetch data using SWR with the v2 API endpoints, handling loading and error states gracefully. Follow the golden path philosophy by keeping the UI minimal and focused on essential workspace information.

Implementation Steps

0. Project Structure Setup

Create new web-ui directory structure:

web-ui/
├── src/
│   ├── app/
│   │   ├── layout.tsx          (root layout with providers)
│   │   ├── page.tsx            (workspace view)
│   │   ├── globals.css         (tailwind + global styles)
│   │   └── (other views)       (prd, tasks, execution, blockers, review)
│   ├── components/
│   │   ├── workspace/          (workspace-specific components)
│   │   ├── shared/             (reusable components)
│   │   └── layout/             (sidebar, header, etc.)
│   ├── lib/
│   │   ├── api.ts              (API client)
│   │   └── hooks.ts            (custom hooks)
│   └── types/
│       └── index.ts            (TypeScript types)
├── package.json
├── tsconfig.json
├── next.config.js
├── tailwind.config.ts
├── postcss.config.js
└── jest.config.js

File: file:web-ui/package.json (new file)

Create package.json with dependencies:

• Next.js 14.1.0
• React 18.2.0
• Shadcn/UI components
• @hugeicons/react 0.3.0
• SWR 2.2.4
• Tailwind CSS 3.4.1
• TypeScript 5.3.3
• Testing libraries (Jest, React Testing Library, MSW)

File: file:web-ui/tsconfig.json (new file)

Configure TypeScript with path aliases (@/* → ./src/*)

File: file:web-ui/next.config.js (new file)

Configure Next.js with App Router, no special plugins needed

File: file:web-ui/tailwind.config.ts (new file)

Use Shadcn/UI Nova template configuration with Tailwind CSS

File: file:web-ui/src/app/layout.tsx (new file)

Create root layout with:

• Metadata (title, description)
• Providers wrapper (SWR, error boundary)
• Global styles import
• Navigation sidebar (placeholder for Phase 3 sidebar)

1. API Client Setup

File: file:web-ui/src/lib/api.ts (new file)

Create workspace API client methods:

import axios from 'axios';

const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000',
  withCredentials: true,
});

export const workspaceApi = {
  // Check if workspace exists at a path
  checkExists: (repoPath: string) => 
    api.get<{ exists: boolean; path: string; state_dir: string | null }>(
      '/api/v2/workspaces/exists', 
      { params: { repo_path: repoPath } }
    ),
  
  // Initialize workspace
  init: (repoPath: string, techStack?: string, detect?: boolean) =>
    api.post<WorkspaceResponse>('/api/v2/workspaces', {
      repo_path: repoPath,
      tech_stack: techStack,
      detect: detect ?? true
    }),
  
  // Get current workspace info
  getCurrent: (workspacePath?: string) =>
    api.get<WorkspaceResponse>('/api/v2/workspaces/current', {
      params: workspacePath ? { workspace_path: workspacePath } : {}
    })
};

export const tasksApi = {
  // Get all tasks with optional filtering
  getAll: (status?: string) =>
    api.get<TaskListResponse>('/api/v2/tasks', {
      params: status ? { status } : {}
    })
};

export default api;

File: file:web-ui/src/types/index.ts (new file)

Create TypeScript types for workspace and task responses:

export interface WorkspaceResponse {
  id: string;
  repo_path: string;
  state_dir: string;
  tech_stack: string | null;
  created_at: string;
}

export interface TaskStatusCounts {
  BACKLOG: number;
  READY: number;
  IN_PROGRESS: number;
  DONE: number;
  BLOCKED: number;
  FAILED: number;
}

export interface Task {
  id: string;
  title: string;
  description: string;
  status: 'BACKLOG' | 'READY' | 'IN_PROGRESS' | 'DONE' | 'BLOCKED' | 'FAILED';
  effort?: number;
  dependencies?: string[];
  created_at: string;
  updated_at: string;
}

export interface TaskListResponse {
  tasks: Task[];
  by_status: TaskStatusCounts;
  total: number;
}

export interface ActivityItem {
  id: string;
  type: 'task_completed' | 'run_started' | 'blocker_raised' | 'workspace_initialized';
  timestamp: string;
  description: string;
  metadata?: Record<string, unknown>;
}

2. Workspace Header Component

File: file:web-ui/src/components/workspace/WorkspaceHeader.tsx (new file)

Create header component with repo path display and initialization button:

• Display repository path using FolderIcon from Hugeicons
• Show "Initialize Workspace" button if workspace doesn't exist
• Use Shadcn Button component with primary variant
• Handle initialization with loading state (disable button, show spinner)
• Display success/error messages using inline alerts
• Props: workspace: WorkspaceResponse | null, isLoading: boolean, onInitialize: () => Promise<void>
• Show workspace path in breadcrumb format: "CodeFRAME / ~/projects/my-app"

3. Workspace Stats Cards Component

File: file:web-ui/src/components/workspace/WorkspaceStatsCards.tsx (new file)

Create stats cards grid using Shadcn Card components:

TechStackCard:

• Icon: Code2Icon from Hugeicons
• Title: "Tech Stack"
• Content: Display detected tech stack or "Not detected" placeholder
• Use text-muted-foreground for empty state
• Props: techStack: string | null

TaskStatsCard:

• Icon: ChecklistIcon from Hugeicons
• Title: "Tasks"
• Content: Display counts by status with colored badges
  • READY: bg-blue-100 text-blue-900
  • IN_PROGRESS: bg-amber-100 text-amber-900
  • DONE: bg-green-100 text-green-900
  • BLOCKED: bg-red-100 text-red-900
  • FAILED: bg-red-200 text-red-900
• Show total count prominently
• Use Shadcn Badge component for status indicators
• Props: counts: TaskStatusCounts

ActiveRunsCard:

• Icon: PlayIcon from Hugeicons
• Title: "Active Runs"
• Content: Display count of currently executing tasks
• Show "0" with muted styling when no active runs
• Add "View Execution" link if count > 0 (navigates to /execution)
• Props: activeRunCount: number

Layout: 3-column grid on desktop (grid-cols-1 md:grid-cols-3), responsive stacking on mobile

4. Recent Activity Feed Component

File: file:web-ui/src/components/workspace/RecentActivityFeed.tsx (new file)

Create activity timeline showing last 5 events:

• Use Shadcn Card component as container
• Title: "Recent Activity" with HistoryIcon from Hugeicons
• Display empty state if no activities: "No recent activity"
• Each ActivityItem shows:
  • Event type icon (task completed, run started, blocker raised, etc.)
  • Timestamp (relative format: "2 hours ago" using date-fns)
  • Description text
  • Optional link to related entity (task, run, blocker)
• Use vertical timeline layout with connecting lines
• Limit to 5 most recent items
• Props: activities: ActivityItem[]

Note: Since the backend doesn't have a dedicated activity endpoint yet, initially render with empty state and add TODO comment for future integration with event streaming.

5. Main Workspace View Page

File: file:web-ui/src/app/page.tsx (new file)

Create the Workspace View as the home/landing page:

Data Fetching:

• Use SWR to fetch workspace status from GET /api/v2/workspaces/current
• Use SWR to fetch task counts from GET /api/v2/tasks (parse by_status field)
• Handle workspace_path from query params or localStorage
• Implement fallback: if no workspace_path, show initialization prompt

Initialization Flow:

1. Check if workspace exists using workspaceApi.checkExists()
2. If not exists, show WorkspaceHeader with init button
3. On init button click, call workspaceApi.init() with auto-detect enabled
4. After successful init, mutate SWR cache to refresh data
5. Show initialized workspace with stats cards

Layout Structure:

<main className="min-h-screen bg-background">
  <div className="max-w-7xl mx-auto px-4 py-8">
    <WorkspaceHeader />
    {isInitialized && (
      <>
        <WorkspaceStatsCards />
        <QuickActions />
        <RecentActivityFeed />
      </>
    )}
  </div>
</main>

Error Handling:

• Show error boundary for critical failures
• Display inline error messages for API failures
• Provide retry buttons for failed operations

Loading States:

• Show skeleton loaders for stats cards while fetching
• Use Spinner component from Hugeicons
• Disable interactive elements during mutations

6. Quick Actions Component

File: file:web-ui/src/components/workspace/QuickActions.tsx (new file)

Create quick navigation links for golden path workflow:

Location: Below WorkspaceStatsCards, above RecentActivityFeed

Create a "Quick Actions" section with buttons:

• "View PRD" → navigates to /prd (use FileTextIcon)
• "Manage Tasks" → navigates to /tasks (use ChecklistIcon)
• "Review Changes" → navigates to /review (use GitBranchIcon)

Use Shadcn Button with variant="outline" for secondary actions
Layout: Horizontal flex row with gap, wrap on mobile
Props: None (static navigation)

7. Responsive Design

Ensure mobile-friendly layout:

• Stats cards: Stack vertically on mobile (grid-cols-1 md:grid-cols-3)
• Quick actions: Wrap buttons on small screens (flex-wrap)
• Activity feed: Full width on all screen sizes
• Use Tailwind responsive prefixes (sm:, md:, lg:)
• Test with viewport widths: 375px (mobile), 768px (tablet), 1024px (desktop)

8. Root Layout & Providers

File: file:web-ui/src/app/layout.tsx (new file)

Create root layout with:

• Metadata (title: "CodeFRAME", description)
• Providers wrapper (SWR configuration, error boundary)
• Global styles import (Tailwind CSS)
• Navigation sidebar placeholder (for Phase 3 sidebar implementation)
• Workspace path breadcrumb in header

File: file:web-ui/src/components/layout/RootLayout.tsx (new file)

Create layout wrapper component:

• Top navigation bar with CodeFRAME logo
• Workspace path breadcrumb
• Placeholder for sidebar (will be implemented in Phase 3 sidebar ticket)
• Main content area with children

9. API Endpoint Corrections

Documentation Update: Note that the ticket's API endpoint references should be corrected:

• ❌ GET /api/v2/workspace/status → ✅ GET /api/v2/workspaces/current
• ❌ POST /api/v2/workspace/init → ✅ POST /api/v2/workspaces
• ✅ GET /api/v2/tasks (correct, already exists)

The implementation uses the actual backend endpoints from file:codeframe/ui/routers/workspace_v2.py and file:codeframe/ui/routers/tasks_v2.py.

10. Testing Considerations

Create test files following existing patterns:

File: file:web-ui/__tests__/components/workspace/WorkspaceHeader.test.tsx (new file)

• Test initialization button visibility based on workspace existence
• Test button click triggers onInitialize callback
• Test loading state during initialization
• Test error message display

File: file:web-ui/__tests__/components/workspace/WorkspaceStatsCards.test.tsx (new file)

• Test rendering of all three cards
• Test task status badge colors match Nova palette
• Test empty states for missing data
• Test active runs link navigation

File: file:web-ui/__tests__/app/page.test.tsx (new file)

• Test SWR data fetching with MSW mocks
• Test initialization flow
• Test error states and retry
• Test responsive layout

Use test infrastructure (Jest, React Testing Library, MSW for API mocking)

11. Environment Configuration

File: file:web-ui/.env.example (new file)

Create environment template:

NEXT_PUBLIC_API_URL=http://localhost:8000

File: file:web-ui/.env.local (development)

Set local API URL for development

12. Build & Deployment Configuration

File: file:web-ui/next.config.js (new file)

Configure Next.js with:

• App Router enabled (default in Next.js 14)
• No special plugins needed
• Image optimization disabled (not needed for Phase 3)

File: file:web-ui/tailwind.config.ts (new file)

Use Shadcn/UI Nova template configuration

File: file:web-ui/postcss.config.js (new file)

Configure PostCSS with Tailwind and Autoprefixer

Component Hierarchy Diagram

graph TD
    A[RootLayout<br/>layout.tsx] --> B[Navigation Bar]
    A --> C[WorkspaceView<br/>page.tsx]
    
    C --> D[WorkspaceHeader]
    C --> E[WorkspaceStatsCards]
    C --> F[QuickActions]
    C --> G[RecentActivityFeed]
    
    D --> D1[RepoPathDisplay]
    D --> D2[InitializeWorkspaceButton]
    
    E --> E1[TechStackCard]
    E --> E2[TaskStatsCard]
    E --> E3[ActiveRunsCard]
    
    E2 --> E2A[Status Badges]
    
    F --> F1[PRD Link]
    F --> F2[Tasks Link]
    F --> F3[Review Link]
    
    G --> G1[ActivityItem[]]
    
    style A fill:#e3f2fd
    style C fill:#e3f2fd
    style D fill:#fff3e0
    style E fill:#fff3e0
    style F fill:#fff3e0
    style G fill:#fff3e0

Loading

Data Flow

sequenceDiagram
    participant User
    participant WorkspaceView
    participant SWR
    participant API
    participant Backend

    User->>WorkspaceView: Navigate to /
    WorkspaceView->>SWR: useSWR('/api/v2/workspaces/current')
    SWR->>API: GET /api/v2/workspaces/current
    API->>Backend: Request workspace info
    
    alt Workspace exists
        Backend-->>API: WorkspaceResponse
        API-->>SWR: Workspace data
        SWR-->>WorkspaceView: Render initialized view
        WorkspaceView->>SWR: useSWR('/api/v2/tasks')
        SWR->>API: GET /api/v2/tasks
        API->>Backend: Request task counts
        Backend-->>API: TaskListResponse with by_status
        API-->>SWR: Task counts
        SWR-->>WorkspaceView: Render stats cards
    else Workspace not found
        Backend-->>API: 404 or empty response
        API-->>SWR: Error/null
        SWR-->>WorkspaceView: Show init button
        User->>WorkspaceView: Click "Initialize Workspace"
        WorkspaceView->>API: POST /api/v2/workspaces
        API->>Backend: Create workspace
        Backend-->>API: WorkspaceResponse
        API-->>WorkspaceView: Success
        WorkspaceView->>SWR: mutate() to refresh
    end

Loading

File Structure Summary

web-ui/
├── src/
│   ├── app/
│   │   ├── layout.tsx                    (root layout with providers)
│   │   ├── page.tsx                      (workspace view - home)
│   │   └── globals.css                   (tailwind + global styles)
│   ├── components/
│   │   ├── workspace/
│   │   │   ├── WorkspaceHeader.tsx
│   │   │   ├── WorkspaceStatsCards.tsx
│   │   │   ├── QuickActions.tsx
│   │   │   └── RecentActivityFeed.tsx
│   │   └── layout/
│   │       └── RootLayout.tsx
│   ├── lib/
│   │   └── api.ts                        (API client)
│   └── types/
│       └── index.ts                      (TypeScript types)
├── __tests__/
│   ├── components/workspace/
│   │   ├── WorkspaceHeader.test.tsx
│   │   └── WorkspaceStatsCards.test.tsx
│   └── app/
│       └── page.test.tsx
├── package.json
├── tsconfig.json
├── next.config.js
├── tailwind.config.ts
├── postcss.config.js
├── jest.config.js
├── .env.example
└── README.md

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a legacy project-based architecture at the root route (`/`) showing a ProjectList component. Phase 3 introduces a workspace-based architecture using v2 API endpoints (`/api/v2/workspaces`, `/api/v2/tasks`). The frontend uses Next.js 14 App Router, Shadcn/UI Nova template, Hugeicons, and SWR for data fetching. The backend workspace API is implemented in `file:codeframe/ui/routers/workspace_v2.py` and tasks API in `file:codeframe/ui/routers/tasks_v2.py`. The Phase 3 architecture document defines a complete golden path UI with 6 core views. A brand new UI structure is required, separate from the legacy pages, to implement the Phase 3 vision.

## Approach

Create a brand new UI application structure alongside the legacy codebase. Establish a new Next.js app directory at `web-ui/` with a fresh component architecture following the Phase 3 specification. Build the Workspace View as the first Phase 3 view, implementing the component hierarchy: WorkspaceView → WorkspaceHeader, WorkspaceStatsCards, RecentActivityFeed. Use Shadcn/UI components (Card, Button, Badge) and Hugeicons for consistency with the Nova template. Implement workspace initialization flow with conditional rendering based on workspace existence. Fetch data using SWR with the v2 API endpoints, handling loading and error states gracefully. Follow the golden path philosophy by keeping the UI minimal and focused on essential workspace information.

## Implementation Steps

### 0. Project Structure Setup

**Create new web-ui directory structure:**

```
web-ui/
├── src/
│   ├── app/
│   │   ├── layout.tsx          (root layout with providers)
│   │   ├── page.tsx            (workspace view)
│   │   ├── globals.css         (tailwind + global styles)
│   │   └── (other views)       (prd, tasks, execution, blockers, review)
│   ├── components/
│   │   ├── workspace/          (workspace-specific components)
│   │   ├── shared/             (reusable components)
│   │   └── layout/             (sidebar, header, etc.)
│   ├── lib/
│   │   ├── api.ts              (API client)
│   │   └── hooks.ts            (custom hooks)
│   └── types/
│       └── index.ts            (TypeScript types)
├── package.json
├── tsconfig.json
├── next.config.js
├── tailwind.config.ts
├── postcss.config.js
└── jest.config.js
```

**File**: `file:web-ui/package.json` (new file)

Create package.json with dependencies:
- Next.js 14.1.0
- React 18.2.0
- Shadcn/UI components
- @hugeicons/react 0.3.0
- SWR 2.2.4
- Tailwind CSS 3.4.1
- TypeScript 5.3.3
- Testing libraries (Jest, React Testing Library, MSW)

**File**: `file:web-ui/tsconfig.json` (new file)

Configure TypeScript with path aliases (`@/*` → `./src/*`)

**File**: `file:web-ui/next.config.js` (new file)

Configure Next.js with App Router, no special plugins needed

**File**: `file:web-ui/tailwind.config.ts` (new file)

Use Shadcn/UI Nova template configuration with Tailwind CSS

**File**: `file:web-ui/src/app/layout.tsx` (new file)

Create root layout with:
- Metadata (title, description)
- Providers wrapper (SWR, error boundary)
- Global styles import
- Navigation sidebar (placeholder for Phase 3 sidebar)

### 1. API Client Setup

**File**: `file:web-ui/src/lib/api.ts` (new file)

Create workspace API client methods:

```typescript
import axios from 'axios';

const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000',
  withCredentials: true,
});

export const workspaceApi = {
  // Check if workspace exists at a path
  checkExists: (repoPath: string) => 
    api.get<{ exists: boolean; path: string; state_dir: string | null }>(
      '/api/v2/workspaces/exists', 
      { params: { repo_path: repoPath } }
    ),
  
  // Initialize workspace
  init: (repoPath: string, techStack?: string, detect?: boolean) =>
    api.post<WorkspaceResponse>('/api/v2/workspaces', {
      repo_path: repoPath,
      tech_stack: techStack,
      detect: detect ?? true
    }),
  
  // Get current workspace info
  getCurrent: (workspacePath?: string) =>
    api.get<WorkspaceResponse>('/api/v2/workspaces/current', {
      params: workspacePath ? { workspace_path: workspacePath } : {}
    })
};

export const tasksApi = {
  // Get all tasks with optional filtering
  getAll: (status?: string) =>
    api.get<TaskListResponse>('/api/v2/tasks', {
      params: status ? { status } : {}
    })
};

export default api;
```

**File**: `file:web-ui/src/types/index.ts` (new file)

Create TypeScript types for workspace and task responses:

```typescript
export interface WorkspaceResponse {
  id: string;
  repo_path: string;
  state_dir: string;
  tech_stack: string | null;
  created_at: string;
}

export interface TaskStatusCounts {
  BACKLOG: number;
  READY: number;
  IN_PROGRESS: number;
  DONE: number;
  BLOCKED: number;
  FAILED: number;
}

export interface Task {
  id: string;
  title: string;
  description: string;
  status: 'BACKLOG' | 'READY' | 'IN_PROGRESS' | 'DONE' | 'BLOCKED' | 'FAILED';
  effort?: number;
  dependencies?: string[];
  created_at: string;
  updated_at: string;
}

export interface TaskListResponse {
  tasks: Task[];
  by_status: TaskStatusCounts;
  total: number;
}

export interface ActivityItem {
  id: string;
  type: 'task_completed' | 'run_started' | 'blocker_raised' | 'workspace_initialized';
  timestamp: string;
  description: string;
  metadata?: Record<string, unknown>;
}
```

### 2. Workspace Header Component

**File**: `file:web-ui/src/components/workspace/WorkspaceHeader.tsx` (new file)

Create header component with repo path display and initialization button:

- Display repository path using `FolderIcon` from Hugeicons
- Show "Initialize Workspace" button if workspace doesn't exist
- Use Shadcn Button component with primary variant
- Handle initialization with loading state (disable button, show spinner)
- Display success/error messages using inline alerts
- Props: `workspace: WorkspaceResponse | null`, `isLoading: boolean`, `onInitialize: () => Promise<void>`
- Show workspace path in breadcrumb format: "CodeFRAME / ~/projects/my-app"

### 3. Workspace Stats Cards Component

**File**: `file:web-ui/src/components/workspace/WorkspaceStatsCards.tsx` (new file)

Create stats cards grid using Shadcn Card components:

**TechStackCard**:
- Icon: `Code2Icon` from Hugeicons
- Title: "Tech Stack"
- Content: Display detected tech stack or "Not detected" placeholder
- Use `text-muted-foreground` for empty state
- Props: `techStack: string | null`

**TaskStatsCard**:
- Icon: `ChecklistIcon` from Hugeicons  
- Title: "Tasks"
- Content: Display counts by status with colored badges
  - READY: `bg-blue-100 text-blue-900`
  - IN_PROGRESS: `bg-amber-100 text-amber-900`
  - DONE: `bg-green-100 text-green-900`
  - BLOCKED: `bg-red-100 text-red-900`
  - FAILED: `bg-red-200 text-red-900`
- Show total count prominently
- Use Shadcn Badge component for status indicators
- Props: `counts: TaskStatusCounts`

**ActiveRunsCard**:
- Icon: `PlayIcon` from Hugeicons
- Title: "Active Runs"
- Content: Display count of currently executing tasks
- Show "0" with muted styling when no active runs
- Add "View Execution" link if count > 0 (navigates to `/execution`)
- Props: `activeRunCount: number`

Layout: 3-column grid on desktop (`grid-cols-1 md:grid-cols-3`), responsive stacking on mobile

### 4. Recent Activity Feed Component

**File**: `file:web-ui/src/components/workspace/RecentActivityFeed.tsx` (new file)

Create activity timeline showing last 5 events:

- Use Shadcn Card component as container
- Title: "Recent Activity" with `HistoryIcon` from Hugeicons
- Display empty state if no activities: "No recent activity"
- Each ActivityItem shows:
  - Event type icon (task completed, run started, blocker raised, etc.)
  - Timestamp (relative format: "2 hours ago" using `date-fns`)
  - Description text
  - Optional link to related entity (task, run, blocker)
- Use vertical timeline layout with connecting lines
- Limit to 5 most recent items
- Props: `activities: ActivityItem[]`

**Note**: Since the backend doesn't have a dedicated activity endpoint yet, initially render with empty state and add TODO comment for future integration with event streaming.

### 5. Main Workspace View Page

**File**: `file:web-ui/src/app/page.tsx` (new file)

Create the Workspace View as the home/landing page:

**Data Fetching**:
- Use SWR to fetch workspace status from `GET /api/v2/workspaces/current`
- Use SWR to fetch task counts from `GET /api/v2/tasks` (parse `by_status` field)
- Handle workspace_path from query params or localStorage
- Implement fallback: if no workspace_path, show initialization prompt

**Initialization Flow**:
1. Check if workspace exists using `workspaceApi.checkExists()`
2. If not exists, show WorkspaceHeader with init button
3. On init button click, call `workspaceApi.init()` with auto-detect enabled
4. After successful init, mutate SWR cache to refresh data
5. Show initialized workspace with stats cards

**Layout Structure**:
```
<main className="min-h-screen bg-background">
  <div className="max-w-7xl mx-auto px-4 py-8">
    <WorkspaceHeader />
    {isInitialized && (
      <>
        <WorkspaceStatsCards />
        <QuickActions />
        <RecentActivityFeed />
      </>
    )}
  </div>
</main>
```

**Error Handling**:
- Show error boundary for critical failures
- Display inline error messages for API failures
- Provide retry buttons for failed operations

**Loading States**:
- Show skeleton loaders for stats cards while fetching
- Use Spinner component from Hugeicons
- Disable interactive elements during mutations

### 6. Quick Actions Component

**File**: `file:web-ui/src/components/workspace/QuickActions.tsx` (new file)

Create quick navigation links for golden path workflow:

**Location**: Below WorkspaceStatsCards, above RecentActivityFeed

Create a "Quick Actions" section with buttons:
- "View PRD" → navigates to `/prd` (use `FileTextIcon`)
- "Manage Tasks" → navigates to `/tasks` (use `ChecklistIcon`)
- "Review Changes" → navigates to `/review` (use `GitBranchIcon`)

Use Shadcn Button with `variant="outline"` for secondary actions
Layout: Horizontal flex row with gap, wrap on mobile
Props: None (static navigation)

### 7. Responsive Design

Ensure mobile-friendly layout:
- Stats cards: Stack vertically on mobile (`grid-cols-1 md:grid-cols-3`)
- Quick actions: Wrap buttons on small screens (`flex-wrap`)
- Activity feed: Full width on all screen sizes
- Use Tailwind responsive prefixes (`sm:`, `md:`, `lg:`)
- Test with viewport widths: 375px (mobile), 768px (tablet), 1024px (desktop)

### 8. Root Layout & Providers

**File**: `file:web-ui/src/app/layout.tsx` (new file)

Create root layout with:
- Metadata (title: "CodeFRAME", description)
- Providers wrapper (SWR configuration, error boundary)
- Global styles import (Tailwind CSS)
- Navigation sidebar placeholder (for Phase 3 sidebar implementation)
- Workspace path breadcrumb in header

**File**: `file:web-ui/src/components/layout/RootLayout.tsx` (new file)

Create layout wrapper component:
- Top navigation bar with CodeFRAME logo
- Workspace path breadcrumb
- Placeholder for sidebar (will be implemented in Phase 3 sidebar ticket)
- Main content area with children

### 9. API Endpoint Corrections

**Documentation Update**: Note that the ticket's API endpoint references should be corrected:

- ❌ `GET /api/v2/workspace/status` → ✅ `GET /api/v2/workspaces/current`
- ❌ `POST /api/v2/workspace/init` → ✅ `POST /api/v2/workspaces`
- ✅ `GET /api/v2/tasks` (correct, already exists)

The implementation uses the actual backend endpoints from `file:codeframe/ui/routers/workspace_v2.py` and `file:codeframe/ui/routers/tasks_v2.py`.

### 10. Testing Considerations

Create test files following existing patterns:

**File**: `file:web-ui/__tests__/components/workspace/WorkspaceHeader.test.tsx` (new file)
- Test initialization button visibility based on workspace existence
- Test button click triggers `onInitialize` callback
- Test loading state during initialization
- Test error message display

**File**: `file:web-ui/__tests__/components/workspace/WorkspaceStatsCards.test.tsx` (new file)
- Test rendering of all three cards
- Test task status badge colors match Nova palette
- Test empty states for missing data
- Test active runs link navigation

**File**: `file:web-ui/__tests__/app/page.test.tsx` (new file)
- Test SWR data fetching with MSW mocks
- Test initialization flow
- Test error states and retry
- Test responsive layout

Use test infrastructure (Jest, React Testing Library, MSW for API mocking)

### 11. Environment Configuration

**File**: `file:web-ui/.env.example` (new file)

Create environment template:
```
NEXT_PUBLIC_API_URL=http://localhost:8000
```

**File**: `file:web-ui/.env.local` (development)

Set local API URL for development

### 12. Build & Deployment Configuration

**File**: `file:web-ui/next.config.js` (new file)

Configure Next.js with:
- App Router enabled (default in Next.js 14)
- No special plugins needed
- Image optimization disabled (not needed for Phase 3)

**File**: `file:web-ui/tailwind.config.ts` (new file)

Use Shadcn/UI Nova template configuration

**File**: `file:web-ui/postcss.config.js` (new file)

Configure PostCSS with Tailwind and Autoprefixer

## Component Hierarchy Diagram

```mermaid
graph TD
    A[RootLayout<br/>layout.tsx] --> B[Navigation Bar]
    A --> C[WorkspaceView<br/>page.tsx]
    
    C --> D[WorkspaceHeader]
    C --> E[WorkspaceStatsCards]
    C --> F[QuickActions]
    C --> G[RecentActivityFeed]
    
    D --> D1[RepoPathDisplay]
    D --> D2[InitializeWorkspaceButton]
    
    E --> E1[TechStackCard]
    E --> E2[TaskStatsCard]
    E --> E3[ActiveRunsCard]
    
    E2 --> E2A[Status Badges]
    
    F --> F1[PRD Link]
    F --> F2[Tasks Link]
    F --> F3[Review Link]
    
    G --> G1[ActivityItem[]]
    
    style A fill:#e3f2fd
    style C fill:#e3f2fd
    style D fill:#fff3e0
    style E fill:#fff3e0
    style F fill:#fff3e0
    style G fill:#fff3e0
```

## Data Flow

```mermaid
sequenceDiagram
    participant User
    participant WorkspaceView
    participant SWR
    participant API
    participant Backend

    User->>WorkspaceView: Navigate to /
    WorkspaceView->>SWR: useSWR('/api/v2/workspaces/current')
    SWR->>API: GET /api/v2/workspaces/current
    API->>Backend: Request workspace info
    
    alt Workspace exists
        Backend-->>API: WorkspaceResponse
        API-->>SWR: Workspace data
        SWR-->>WorkspaceView: Render initialized view
        WorkspaceView->>SWR: useSWR('/api/v2/tasks')
        SWR->>API: GET /api/v2/tasks
        API->>Backend: Request task counts
        Backend-->>API: TaskListResponse with by_status
        API-->>SWR: Task counts
        SWR-->>WorkspaceView: Render stats cards
    else Workspace not found
        Backend-->>API: 404 or empty response
        API-->>SWR: Error/null
        SWR-->>WorkspaceView: Show init button
        User->>WorkspaceView: Click "Initialize Workspace"
        WorkspaceView->>API: POST /api/v2/workspaces
        API->>Backend: Create workspace
        Backend-->>API: WorkspaceResponse
        API-->>WorkspaceView: Success
        WorkspaceView->>SWR: mutate() to refresh
    end
```

## File Structure Summary

```
web-ui/
├── src/
│   ├── app/
│   │   ├── layout.tsx                    (root layout with providers)
│   │   ├── page.tsx                      (workspace view - home)
│   │   └── globals.css                   (tailwind + global styles)
│   ├── components/
│   │   ├── workspace/
│   │   │   ├── WorkspaceHeader.tsx
│   │   │   ├── WorkspaceStatsCards.tsx
│   │   │   ├── QuickActions.tsx
│   │   │   └── RecentActivityFeed.tsx
│   │   └── layout/
│   │       └── RootLayout.tsx
│   ├── lib/
│   │   └── api.ts                        (API client)
│   └── types/
│       └── index.ts                      (TypeScript types)
├── __tests__/
│   ├── components/workspace/
│   │   ├── WorkspaceHeader.test.tsx
│   │   └── WorkspaceStatsCards.test.tsx
│   └── app/
│       └── page.test.tsx
├── package.json
├── tsconfig.json
├── next.config.js
├── tailwind.config.ts
├── postcss.config.js
├── jest.config.js
├── .env.example
└── README.md
```

---

Execution Information

Branch: main
Commit: b252361

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[frankbria]

The implementation plan should include the creation of a brand new UI - not use the existing legacy/ui/ pages. The routes will be root, but brand new pages need to be created.

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

Previous Plan

Observations

The codebase has a legacy project-based architecture at the root route (/) showing a ProjectList component. Phase 3 introduces a workspace-based architecture using v2 API endpoints (/api/v2/workspaces, /api/v2/tasks). The frontend already uses Next.js 14 App Router, Shadcn/UI Nova template, Hugeicons, and SWR for data fetching. The backend workspace API is implemented in file:codeframe/ui/routers/workspace_v2.py and tasks API in file:codeframe/ui/routers/tasks_v2.py. Note: The ticket's API endpoint references need minor corrections to match actual backend routes.

Approach

Replace the current project-based home page with a new Workspace View that initializes and displays workspace state. Create a component hierarchy matching the Phase 3 architecture specification: WorkspaceView → WorkspaceHeader, WorkspaceStatsCards, RecentActivityFeed. Use existing Shadcn/UI components (Card, Button, Badge) and Hugeicons for consistency. Implement workspace initialization flow with conditional rendering based on workspace existence. Fetch data using SWR with the v2 API endpoints, handling loading and error states gracefully. Follow the golden path philosophy by keeping the UI minimal and focused on essential workspace information.

Implementation Steps

1. API Client Setup

File: file:legacy/web-ui/src/lib/api.ts

Add workspace API client methods to the existing API module:

export const workspaceApi = {
  // Check if workspace exists at a path
  checkExists: (repoPath: string) => 
    api.get<{ exists: boolean; path: string; state_dir: string | null }>(
      '/api/v2/workspaces/exists', 
      { params: { repo_path: repoPath } }
    ),
  
  // Initialize workspace
  init: (repoPath: string, techStack?: string, detect?: boolean) =>
    api.post<WorkspaceResponse>('/api/v2/workspaces', {
      repo_path: repoPath,
      tech_stack: techStack,
      detect: detect ?? true
    }),
  
  // Get current workspace info
  getCurrent: (workspacePath?: string) =>
    api.get<WorkspaceResponse>('/api/v2/workspaces/current', {
      params: workspacePath ? { workspace_path: workspacePath } : {}
    })
}

File: file:legacy/web-ui/src/types/workspace.ts (new file)

Create TypeScript types for workspace responses:

export interface WorkspaceResponse {
  id: string;
  repo_path: string;
  state_dir: string;
  tech_stack: string | null;
  created_at: string;
}

export interface TaskStatusCounts {
  BACKLOG: number;
  READY: number;
  IN_PROGRESS: number;
  DONE: number;
  BLOCKED: number;
  FAILED: number;
}

2. Workspace Header Component

File: file:legacy/web-ui/src/components/workspace/WorkspaceHeader.tsx (new file)

Create header component with repo path display and initialization button:

• Display repository path using FolderIcon from Hugeicons
• Show "Initialize Workspace" button if workspace doesn't exist
• Use Shadcn Button component with primary variant
• Handle initialization with loading state (disable button, show spinner)
• Display success/error messages using toast or inline alerts
• Props: repoPath: string, isInitialized: boolean, onInitialize: () => Promise<void>

3. Workspace Stats Cards Component

File: file:legacy/web-ui/src/components/workspace/WorkspaceStatsCards.tsx (new file)

Create stats cards grid using Shadcn Card components:

TechStackCard:

• Icon: CodeIcon from Hugeicons
• Title: "Tech Stack"
• Content: Display detected tech stack or "Not detected" placeholder
• Use text-muted-foreground for empty state

TaskStatsCard:

• Icon: TaskIcon from Hugeicons
• Title: "Tasks"
• Content: Display counts by status with colored badges
  • READY: bg-primary/10 text-primary
  • IN_PROGRESS: bg-secondary/10 text-secondary
  • DONE: bg-secondary text-secondary-foreground
  • BLOCKED: bg-destructive/10 text-destructive
  • FAILED: bg-destructive text-destructive-foreground
• Show total count prominently
• Use Shadcn Badge component for status indicators

ActiveRunsCard:

• Icon: PlayIcon from Hugeicons
• Title: "Active Runs"
• Content: Display count of currently executing tasks
• Show "0" with muted styling when no active runs
• Add "View Execution" link if count > 0 (navigates to /execution)

Layout: 3-column grid on desktop (grid-cols-1 md:grid-cols-3), responsive stacking on mobile

4. Recent Activity Feed Component

File: file:legacy/web-ui/src/components/workspace/RecentActivityFeed.tsx (new file)

Create activity timeline showing last 5 events:

• Use Shadcn Card component as container
• Title: "Recent Activity" with ActivityIcon from Hugeicons
• Display empty state if no activities: "No recent activity"
• Each ActivityItem shows:
  • Event type icon (task completed, run started, blocker raised, etc.)
  • Timestamp (relative format: "2 hours ago" using date-fns)
  • Description text
  • Optional link to related entity (task, run, blocker)
• Use vertical timeline layout with connecting lines
• Limit to 5 most recent items
• Props: activities: ActivityItem[]

Note: Since the backend doesn't have a dedicated activity endpoint yet, initially render with empty state and add TODO comment for future integration.

5. Main Workspace View Page

File: file:legacy/web-ui/src/app/page.tsx

Replace existing ProjectList with WorkspaceView:

Data Fetching:

• Use SWR to fetch workspace status from GET /api/v2/workspaces/current
• Use SWR to fetch task counts from GET /api/v2/tasks (parse by_status field)
• Handle workspace_path from query params or localStorage
• Implement fallback: if no workspace_path, show initialization prompt

Initialization Flow:

1. Check if workspace exists using workspaceApi.checkExists()
2. If not exists, show WorkspaceHeader with init button
3. On init button click, call workspaceApi.init() with auto-detect enabled
4. After successful init, mutate SWR cache to refresh data
5. Show initialized workspace with stats cards

Layout Structure:

<main className="min-h-screen bg-background">
  <div className="max-w-7xl mx-auto px-4 py-8">
    <WorkspaceHeader />
    {isInitialized && (
      <>
        <WorkspaceStatsCards />
        <RecentActivityFeed />
      </>
    )}
  </div>
</main>

Error Handling:

• Show error boundary for critical failures
• Display inline error messages for API failures
• Provide retry buttons for failed operations

Loading States:

• Show skeleton loaders for stats cards while fetching
• Use Spinner component from existing codebase
• Disable interactive elements during mutations

6. Quick Navigation Links

Add navigation links to WorkspaceView for golden path workflow:

Location: Below WorkspaceStatsCards, above RecentActivityFeed

Create a "Quick Actions" section with buttons:

• "View PRD" → navigates to /prd (use DocumentIcon)
• "Manage Tasks" → navigates to /tasks (use TaskIcon)
• "Review Changes" → navigates to /review (use GitBranchIcon)

Use Shadcn Button with variant="outline" for secondary actions
Layout: Horizontal flex row with gap, wrap on mobile

7. Responsive Design

Ensure mobile-friendly layout:

• Stats cards: Stack vertically on mobile (grid-cols-1 md:grid-cols-3)
• Quick actions: Wrap buttons on small screens (flex-wrap)
• Activity feed: Full width on all screen sizes
• Use Tailwind responsive prefixes (sm:, md:, lg:)
• Test with viewport widths: 375px (mobile), 768px (tablet), 1024px (desktop)

8. Update Navigation Component

File: file:legacy/web-ui/src/components/Navigation.tsx

Update to support Phase 3 sidebar navigation (future-proofing):

• Keep current top bar for now (Phase 3 sidebar will be separate ticket)
• Update "CodeFRAME" logo link to point to / (workspace home)
• Add workspace path indicator in breadcrumb style
• Example: "CodeFRAME / ~/projects/my-app"

9. API Endpoint Corrections

Documentation Update: Note that the ticket's API endpoint references should be corrected:

• ❌ GET /api/v2/workspace/status → ✅ GET /api/v2/workspaces/current
• ❌ POST /api/v2/workspace/init → ✅ POST /api/v2/workspaces
• ✅ GET /api/v2/tasks (correct, already exists)

The implementation should use the actual backend endpoints from file:codeframe/ui/routers/workspace_v2.py and file:codeframe/ui/routers/tasks_v2.py.

10. Testing Considerations

Create test files following existing patterns:

File: file:legacy/web-ui/__tests__/components/workspace/WorkspaceHeader.test.tsx

• Test initialization button visibility based on isInitialized prop
• Test button click triggers onInitialize callback
• Test loading state during initialization

File: file:legacy/web-ui/__tests__/components/workspace/WorkspaceStatsCards.test.tsx

• Test rendering of all three cards
• Test task status badge colors match Nova palette
• Test empty states for missing data

File: file:legacy/web-ui/__tests__/app/page.test.tsx

• Update existing test to match new WorkspaceView
• Test SWR data fetching with MSW mocks
• Test initialization flow
• Test error states

Use existing test infrastructure (Jest, React Testing Library, MSW for API mocking)

Component Hierarchy Diagram

graph TD
    A[WorkspaceView<br/>page.tsx] --> B[WorkspaceHeader]
    A --> C[WorkspaceStatsCards]
    A --> D[Quick Actions]
    A --> E[RecentActivityFeed]
    
    B --> B1[RepoPathDisplay]
    B --> B2[InitializeWorkspaceButton]
    
    C --> C1[TechStackCard]
    C --> C2[TaskStatsCard]
    C --> C3[ActiveRunsCard]
    
    C2 --> C2A[Status Badges]
    
    E --> E1[ActivityItem[]]
    
    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#fff3e0
    style D fill:#fff3e0
    style E fill:#fff3e0

Loading

Data Flow

sequenceDiagram
    participant User
    participant WorkspaceView
    participant SWR
    participant API
    participant Backend

    User->>WorkspaceView: Navigate to /
    WorkspaceView->>SWR: useSWR('/api/v2/workspaces/current')
    SWR->>API: GET /api/v2/workspaces/current
    API->>Backend: Request workspace info
    
    alt Workspace exists
        Backend-->>API: WorkspaceResponse
        API-->>SWR: Workspace data
        SWR-->>WorkspaceView: Render initialized view
        WorkspaceView->>SWR: useSWR('/api/v2/tasks')
        SWR->>API: GET /api/v2/tasks
        API->>Backend: Request task counts
        Backend-->>API: TaskListResponse with by_status
        API-->>SWR: Task counts
        SWR-->>WorkspaceView: Render stats cards
    else Workspace not found
        Backend-->>API: 404 or empty response
        API-->>SWR: Error/null
        SWR-->>WorkspaceView: Show init button
        User->>WorkspaceView: Click "Initialize Workspace"
        WorkspaceView->>API: POST /api/v2/workspaces
        API->>Backend: Create workspace
        Backend-->>API: WorkspaceResponse
        API-->>WorkspaceView: Success
        WorkspaceView->>SWR: mutate() to refresh
    end

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a legacy project-based architecture at the root route (`/`) showing a ProjectList component. Phase 3 introduces a workspace-based architecture using v2 API endpoints (`/api/v2/workspaces`, `/api/v2/tasks`). The frontend already uses Next.js 14 App Router, Shadcn/UI Nova template, Hugeicons, and SWR for data fetching. The backend workspace API is implemented in `file:codeframe/ui/routers/workspace_v2.py` and tasks API in `file:codeframe/ui/routers/tasks_v2.py`. Note: The ticket's API endpoint references need minor corrections to match actual backend routes.

## Approach

Replace the current project-based home page with a new Workspace View that initializes and displays workspace state. Create a component hierarchy matching the Phase 3 architecture specification: WorkspaceView → WorkspaceHeader, WorkspaceStatsCards, RecentActivityFeed. Use existing Shadcn/UI components (Card, Button, Badge) and Hugeicons for consistency. Implement workspace initialization flow with conditional rendering based on workspace existence. Fetch data using SWR with the v2 API endpoints, handling loading and error states gracefully. Follow the golden path philosophy by keeping the UI minimal and focused on essential workspace information.

## Implementation Steps

### 1. API Client Setup

**File**: `file:legacy/web-ui/src/lib/api.ts`

Add workspace API client methods to the existing API module:

```typescript
export const workspaceApi = {
  // Check if workspace exists at a path
  checkExists: (repoPath: string) => 
    api.get<{ exists: boolean; path: string; state_dir: string | null }>(
      '/api/v2/workspaces/exists', 
      { params: { repo_path: repoPath } }
    ),
  
  // Initialize workspace
  init: (repoPath: string, techStack?: string, detect?: boolean) =>
    api.post<WorkspaceResponse>('/api/v2/workspaces', {
      repo_path: repoPath,
      tech_stack: techStack,
      detect: detect ?? true
    }),
  
  // Get current workspace info
  getCurrent: (workspacePath?: string) =>
    api.get<WorkspaceResponse>('/api/v2/workspaces/current', {
      params: workspacePath ? { workspace_path: workspacePath } : {}
    })
}
```

**File**: `file:legacy/web-ui/src/types/workspace.ts` (new file)

Create TypeScript types for workspace responses:

```typescript
export interface WorkspaceResponse {
  id: string;
  repo_path: string;
  state_dir: string;
  tech_stack: string | null;
  created_at: string;
}

export interface TaskStatusCounts {
  BACKLOG: number;
  READY: number;
  IN_PROGRESS: number;
  DONE: number;
  BLOCKED: number;
  FAILED: number;
}
```

### 2. Workspace Header Component

**File**: `file:legacy/web-ui/src/components/workspace/WorkspaceHeader.tsx` (new file)

Create header component with repo path display and initialization button:

- Display repository path using `FolderIcon` from Hugeicons
- Show "Initialize Workspace" button if workspace doesn't exist
- Use Shadcn Button component with primary variant
- Handle initialization with loading state (disable button, show spinner)
- Display success/error messages using toast or inline alerts
- Props: `repoPath: string`, `isInitialized: boolean`, `onInitialize: () => Promise<void>`

### 3. Workspace Stats Cards Component

**File**: `file:legacy/web-ui/src/components/workspace/WorkspaceStatsCards.tsx` (new file)

Create stats cards grid using Shadcn Card components:

**TechStackCard**:
- Icon: `CodeIcon` from Hugeicons
- Title: "Tech Stack"
- Content: Display detected tech stack or "Not detected" placeholder
- Use `text-muted-foreground` for empty state

**TaskStatsCard**:
- Icon: `TaskIcon` from Hugeicons  
- Title: "Tasks"
- Content: Display counts by status with colored badges
  - READY: `bg-primary/10 text-primary`
  - IN_PROGRESS: `bg-secondary/10 text-secondary`
  - DONE: `bg-secondary text-secondary-foreground`
  - BLOCKED: `bg-destructive/10 text-destructive`
  - FAILED: `bg-destructive text-destructive-foreground`
- Show total count prominently
- Use Shadcn Badge component for status indicators

**ActiveRunsCard**:
- Icon: `PlayIcon` from Hugeicons
- Title: "Active Runs"
- Content: Display count of currently executing tasks
- Show "0" with muted styling when no active runs
- Add "View Execution" link if count > 0 (navigates to `/execution`)

Layout: 3-column grid on desktop (`grid-cols-1 md:grid-cols-3`), responsive stacking on mobile

### 4. Recent Activity Feed Component

**File**: `file:legacy/web-ui/src/components/workspace/RecentActivityFeed.tsx` (new file)

Create activity timeline showing last 5 events:

- Use Shadcn Card component as container
- Title: "Recent Activity" with `ActivityIcon` from Hugeicons
- Display empty state if no activities: "No recent activity"
- Each ActivityItem shows:
  - Event type icon (task completed, run started, blocker raised, etc.)
  - Timestamp (relative format: "2 hours ago" using `date-fns`)
  - Description text
  - Optional link to related entity (task, run, blocker)
- Use vertical timeline layout with connecting lines
- Limit to 5 most recent items
- Props: `activities: ActivityItem[]`

**Note**: Since the backend doesn't have a dedicated activity endpoint yet, initially render with empty state and add TODO comment for future integration.

### 5. Main Workspace View Page

**File**: `file:legacy/web-ui/src/app/page.tsx`

Replace existing ProjectList with WorkspaceView:

**Data Fetching**:
- Use SWR to fetch workspace status from `GET /api/v2/workspaces/current`
- Use SWR to fetch task counts from `GET /api/v2/tasks` (parse `by_status` field)
- Handle workspace_path from query params or localStorage
- Implement fallback: if no workspace_path, show initialization prompt

**Initialization Flow**:
1. Check if workspace exists using `workspaceApi.checkExists()`
2. If not exists, show WorkspaceHeader with init button
3. On init button click, call `workspaceApi.init()` with auto-detect enabled
4. After successful init, mutate SWR cache to refresh data
5. Show initialized workspace with stats cards

**Layout Structure**:
```
<main className="min-h-screen bg-background">
  <div className="max-w-7xl mx-auto px-4 py-8">
    <WorkspaceHeader />
    {isInitialized && (
      <>
        <WorkspaceStatsCards />
        <RecentActivityFeed />
      </>
    )}
  </div>
</main>
```

**Error Handling**:
- Show error boundary for critical failures
- Display inline error messages for API failures
- Provide retry buttons for failed operations

**Loading States**:
- Show skeleton loaders for stats cards while fetching
- Use Spinner component from existing codebase
- Disable interactive elements during mutations

### 6. Quick Navigation Links

Add navigation links to WorkspaceView for golden path workflow:

**Location**: Below WorkspaceStatsCards, above RecentActivityFeed

Create a "Quick Actions" section with buttons:
- "View PRD" → navigates to `/prd` (use `DocumentIcon`)
- "Manage Tasks" → navigates to `/tasks` (use `TaskIcon`)
- "Review Changes" → navigates to `/review` (use `GitBranchIcon`)

Use Shadcn Button with `variant="outline"` for secondary actions
Layout: Horizontal flex row with gap, wrap on mobile

### 7. Responsive Design

Ensure mobile-friendly layout:
- Stats cards: Stack vertically on mobile (`grid-cols-1 md:grid-cols-3`)
- Quick actions: Wrap buttons on small screens (`flex-wrap`)
- Activity feed: Full width on all screen sizes
- Use Tailwind responsive prefixes (`sm:`, `md:`, `lg:`)
- Test with viewport widths: 375px (mobile), 768px (tablet), 1024px (desktop)

### 8. Update Navigation Component

**File**: `file:legacy/web-ui/src/components/Navigation.tsx`

Update to support Phase 3 sidebar navigation (future-proofing):

- Keep current top bar for now (Phase 3 sidebar will be separate ticket)
- Update "CodeFRAME" logo link to point to `/` (workspace home)
- Add workspace path indicator in breadcrumb style
- Example: "CodeFRAME / ~/projects/my-app"

### 9. API Endpoint Corrections

**Documentation Update**: Note that the ticket's API endpoint references should be corrected:

- ❌ `GET /api/v2/workspace/status` → ✅ `GET /api/v2/workspaces/current`
- ❌ `POST /api/v2/workspace/init` → ✅ `POST /api/v2/workspaces`
- ✅ `GET /api/v2/tasks` (correct, already exists)

The implementation should use the actual backend endpoints from `file:codeframe/ui/routers/workspace_v2.py` and `file:codeframe/ui/routers/tasks_v2.py`.

### 10. Testing Considerations

Create test files following existing patterns:

**File**: `file:legacy/web-ui/__tests__/components/workspace/WorkspaceHeader.test.tsx`
- Test initialization button visibility based on `isInitialized` prop
- Test button click triggers `onInitialize` callback
- Test loading state during initialization

**File**: `file:legacy/web-ui/__tests__/components/workspace/WorkspaceStatsCards.test.tsx`
- Test rendering of all three cards
- Test task status badge colors match Nova palette
- Test empty states for missing data

**File**: `file:legacy/web-ui/__tests__/app/page.test.tsx`
- Update existing test to match new WorkspaceView
- Test SWR data fetching with MSW mocks
- Test initialization flow
- Test error states

Use existing test infrastructure (Jest, React Testing Library, MSW for API mocking)

## Component Hierarchy Diagram

```mermaid
graph TD
    A[WorkspaceView<br/>page.tsx] --> B[WorkspaceHeader]
    A --> C[WorkspaceStatsCards]
    A --> D[Quick Actions]
    A --> E[RecentActivityFeed]
    
    B --> B1[RepoPathDisplay]
    B --> B2[InitializeWorkspaceButton]
    
    C --> C1[TechStackCard]
    C --> C2[TaskStatsCard]
    C --> C3[ActiveRunsCard]
    
    C2 --> C2A[Status Badges]
    
    E --> E1[ActivityItem[]]
    
    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#fff3e0
    style D fill:#fff3e0
    style E fill:#fff3e0
```

## Data Flow

```mermaid
sequenceDiagram
    participant User
    participant WorkspaceView
    participant SWR
    participant API
    participant Backend

    User->>WorkspaceView: Navigate to /
    WorkspaceView->>SWR: useSWR('/api/v2/workspaces/current')
    SWR->>API: GET /api/v2/workspaces/current
    API->>Backend: Request workspace info
    
    alt Workspace exists
        Backend-->>API: WorkspaceResponse
        API-->>SWR: Workspace data
        SWR-->>WorkspaceView: Render initialized view
        WorkspaceView->>SWR: useSWR('/api/v2/tasks')
        SWR->>API: GET /api/v2/tasks
        API->>Backend: Request task counts
        Backend-->>API: TaskListResponse with by_status
        API-->>SWR: Task counts
        SWR-->>WorkspaceView: Render stats cards
    else Workspace not found
        Backend-->>API: 404 or empty response
        API-->>SWR: Error/null
        SWR-->>WorkspaceView: Show init button
        User->>WorkspaceView: Click "Initialize Workspace"
        WorkspaceView->>API: POST /api/v2/workspaces
        API->>Backend: Create workspace
        Backend-->>API: WorkspaceResponse
        API-->>WorkspaceView: Success
        WorkspaceView->>SWR: mutate() to refresh
    end
```

---

Execution Information

Branch: main
Commit: b252361

New Plan

Observations

The codebase has a legacy project-based architecture at the root route (/) showing a ProjectList component. Phase 3 introduces a workspace-based architecture using v2 API endpoints (/api/v2/workspaces, /api/v2/tasks). The frontend uses Next.js 14 App Router, Shadcn/UI Nova template, Hugeicons, and SWR for data fetching. The backend workspace API is implemented in file:codeframe/ui/routers/workspace_v2.py and tasks API in file:codeframe/ui/routers/tasks_v2.py. The Phase 3 architecture document defines a complete golden path UI with 6 core views. A brand new UI structure is required, separate from the legacy pages, to implement the Phase 3 vision.

Approach

Create a brand new UI application structure alongside the legacy codebase. Establish a new Next.js app directory at web-ui/ with a fresh component architecture following the Phase 3 specification. Build the Workspace View as the first Phase 3 view, implementing the component hierarchy: WorkspaceView → WorkspaceHeader, WorkspaceStatsCards, RecentActivityFeed. Use Shadcn/UI components (Card, Button, Badge) and Hugeicons for consistency with the Nova template. Implement workspace initialization flow with conditional rendering based on workspace existence. Fetch data using SWR with the v2 API endpoints, handling loading and error states gracefully. Follow the golden path philosophy by keeping the UI minimal and focused on essential workspace information.

Implementation Steps

0. Project Structure Setup

Create new web-ui directory structure:

web-ui/
├── src/
│   ├── app/
│   │   ├── layout.tsx          (root layout with providers)
│   │   ├── page.tsx            (workspace view)
│   │   ├── globals.css         (tailwind + global styles)
│   │   └── (other views)       (prd, tasks, execution, blockers, review)
│   ├── components/
│   │   ├── workspace/          (workspace-specific components)
│   │   ├── shared/             (reusable components)
│   │   └── layout/             (sidebar, header, etc.)
│   ├── lib/
│   │   ├── api.ts              (API client)
│   │   └── hooks.ts            (custom hooks)
│   └── types/
│       └── index.ts            (TypeScript types)
├── package.json
├── tsconfig.json
├── next.config.js
├── tailwind.config.ts
├── postcss.config.js
└── jest.config.js

File: file:web-ui/package.json (new file)

Create package.json with dependencies:

• Next.js 14.1.0
• React 18.2.0
• Shadcn/UI components
• @hugeicons/react 0.3.0
• SWR 2.2.4
• Tailwind CSS 3.4.1
• TypeScript 5.3.3
• Testing libraries (Jest, React Testing Library, MSW)

File: file:web-ui/tsconfig.json (new file)

Configure TypeScript with path aliases (@/* → ./src/*)

File: file:web-ui/next.config.js (new file)

Configure Next.js with App Router, no special plugins needed

File: file:web-ui/tailwind.config.ts (new file)

Use Shadcn/UI Nova template configuration with Tailwind CSS

File: file:web-ui/src/app/layout.tsx (new file)

Create root layout with:

• Metadata (title, description)
• Providers wrapper (SWR, error boundary)
• Global styles import
• Navigation sidebar (placeholder for Phase 3 sidebar)

1. API Client Setup

File: file:web-ui/src/lib/api.ts (new file)

Create workspace API client methods:

import axios from 'axios';

const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000',
  withCredentials: true,
});

export const workspaceApi = {
  // Check if workspace exists at a path
  checkExists: (repoPath: string) => 
    api.get<{ exists: boolean; path: string; state_dir: string | null }>(
      '/api/v2/workspaces/exists', 
      { params: { repo_path: repoPath } }
    ),
  
  // Initialize workspace
  init: (repoPath: string, techStack?: string, detect?: boolean) =>
    api.post<WorkspaceResponse>('/api/v2/workspaces', {
      repo_path: repoPath,
      tech_stack: techStack,
      detect: detect ?? true
    }),
  
  // Get current workspace info
  getCurrent: (workspacePath?: string) =>
    api.get<WorkspaceResponse>('/api/v2/workspaces/current', {
      params: workspacePath ? { workspace_path: workspacePath } : {}
    })
};

export const tasksApi = {
  // Get all tasks with optional filtering
  getAll: (status?: string) =>
    api.get<TaskListResponse>('/api/v2/tasks', {
      params: status ? { status } : {}
    })
};

export default api;

File: file:web-ui/src/types/index.ts (new file)

Create TypeScript types for workspace and task responses:

export interface WorkspaceResponse {
  id: string;
  repo_path: string;
  state_dir: string;
  tech_stack: string | null;
  created_at: string;
}

export interface TaskStatusCounts {
  BACKLOG: number;
  READY: number;
  IN_PROGRESS: number;
  DONE: number;
  BLOCKED: number;
  FAILED: number;
}

export interface Task {
  id: string;
  title: string;
  description: string;
  status: 'BACKLOG' | 'READY' | 'IN_PROGRESS' | 'DONE' | 'BLOCKED' | 'FAILED';
  effort?: number;
  dependencies?: string[];
  created_at: string;
  updated_at: string;
}

export interface TaskListResponse {
  tasks: Task[];
  by_status: TaskStatusCounts;
  total: number;
}

export interface ActivityItem {
  id: string;
  type: 'task_completed' | 'run_started' | 'blocker_raised' | 'workspace_initialized';
  timestamp: string;
  description: string;
  metadata?: Record<string, unknown>;
}

2. Workspace Header Component

File: file:web-ui/src/components/workspace/WorkspaceHeader.tsx (new file)

Create header component with repo path display and initialization button:

• Display repository path using FolderIcon from Hugeicons
• Show "Initialize Workspace" button if workspace doesn't exist
• Use Shadcn Button component with primary variant
• Handle initialization with loading state (disable button, show spinner)
• Display success/error messages using inline alerts
• Props: workspace: WorkspaceResponse | null, isLoading: boolean, onInitialize: () => Promise<void>
• Show workspace path in breadcrumb format: "CodeFRAME / ~/projects/my-app"

3. Workspace Stats Cards Component

File: file:web-ui/src/components/workspace/WorkspaceStatsCards.tsx (new file)

Create stats cards grid using Shadcn Card components:

TechStackCard:

• Icon: Code2Icon from Hugeicons
• Title: "Tech Stack"
• Content: Display detected tech stack or "Not detected" placeholder
• Use text-muted-foreground for empty state
• Props: techStack: string | null

TaskStatsCard:

• Icon: ChecklistIcon from Hugeicons
• Title: "Tasks"
• Content: Display counts by status with colored badges
  • READY: bg-blue-100 text-blue-900
  • IN_PROGRESS: bg-amber-100 text-amber-900
  • DONE: bg-green-100 text-green-900
  • BLOCKED: bg-red-100 text-red-900
  • FAILED: bg-red-200 text-red-900
• Show total count prominently
• Use Shadcn Badge component for status indicators
• Props: counts: TaskStatusCounts

ActiveRunsCard:

• Icon: PlayIcon from Hugeicons
• Title: "Active Runs"
• Content: Display count of currently executing tasks
• Show "0" with muted styling when no active runs
• Add "View Execution" link if count > 0 (navigates to /execution)
• Props: activeRunCount: number

Layout: 3-column grid on desktop (grid-cols-1 md:grid-cols-3), responsive stacking on mobile

4. Recent Activity Feed Component

File: file:web-ui/src/components/workspace/RecentActivityFeed.tsx (new file)

Create activity timeline showing last 5 events:

• Use Shadcn Card component as container
• Title: "Recent Activity" with HistoryIcon from Hugeicons
• Display empty state if no activities: "No recent activity"
• Each ActivityItem shows:
  • Event type icon (task completed, run started, blocker raised, etc.)
  • Timestamp (relative format: "2 hours ago" using date-fns)
  • Description text
  • Optional link to related entity (task, run, blocker)
• Use vertical timeline layout with connecting lines
• Limit to 5 most recent items
• Props: activities: ActivityItem[]

Note: Since the backend doesn't have a dedicated activity endpoint yet, initially render with empty state and add TODO comment for future integration with event streaming.

5. Main Workspace View Page

File: file:web-ui/src/app/page.tsx (new file)

Create the Workspace View as the home/landing page:

Data Fetching:

• Use SWR to fetch workspace status from GET /api/v2/workspaces/current
• Use SWR to fetch task counts from GET /api/v2/tasks (parse by_status field)
• Handle workspace_path from query params or localStorage
• Implement fallback: if no workspace_path, show initialization prompt

Initialization Flow:

1. Check if workspace exists using workspaceApi.checkExists()
2. If not exists, show WorkspaceHeader with init button
3. On init button click, call workspaceApi.init() with auto-detect enabled
4. After successful init, mutate SWR cache to refresh data
5. Show initialized workspace with stats cards

Layout Structure:

<main className="min-h-screen bg-background">
  <div className="max-w-7xl mx-auto px-4 py-8">
    <WorkspaceHeader />
    {isInitialized && (
      <>
        <WorkspaceStatsCards />
        <QuickActions />
        <RecentActivityFeed />
      </>
    )}
  </div>
</main>

Error Handling:

• Show error boundary for critical failures
• Display inline error messages for API failures
• Provide retry buttons for failed operations

Loading States:

• Show skeleton loaders for stats cards while fetching
• Use Spinner component from Hugeicons
• Disable interactive elements during mutations

6. Quick Actions Component

File: file:web-ui/src/components/workspace/QuickActions.tsx (new file)

Create quick navigation links for golden path workflow:

Location: Below WorkspaceStatsCards, above RecentActivityFeed

Create a "Quick Actions" section with buttons:

• "View PRD" → navigates to /prd (use FileTextIcon)
• "Manage Tasks" → navigates to /tasks (use ChecklistIcon)
• "Review Changes" → navigates to /review (use GitBranchIcon)

Use Shadcn Button with variant="outline" for secondary actions
Layout: Horizontal flex row with gap, wrap on mobile
Props: None (static navigation)

7. Responsive Design

Ensure mobile-friendly layout:

• Stats cards: Stack vertically on mobile (grid-cols-1 md:grid-cols-3)
• Quick actions: Wrap buttons on small screens (flex-wrap)
• Activity feed: Full width on all screen sizes
• Use Tailwind responsive prefixes (sm:, md:, lg:)
• Test with viewport widths: 375px (mobile), 768px (tablet), 1024px (desktop)

8. Root Layout & Providers

File: file:web-ui/src/app/layout.tsx (new file)

Create root layout with:

• Metadata (title: "CodeFRAME", description)
• Providers wrapper (SWR configuration, error boundary)
• Global styles import (Tailwind CSS)
• Navigation sidebar placeholder (for Phase 3 sidebar implementation)
• Workspace path breadcrumb in header

File: file:web-ui/src/components/layout/RootLayout.tsx (new file)

Create layout wrapper component:

• Top navigation bar with CodeFRAME logo
• Workspace path breadcrumb
• Placeholder for sidebar (will be implemented in Phase 3 sidebar ticket)
• Main content area with children

9. API Endpoint Corrections

Documentation Update: Note that the ticket's API endpoint references should be corrected:

• ❌ GET /api/v2/workspace/status → ✅ GET /api/v2/workspaces/current
• ❌ POST /api/v2/workspace/init → ✅ POST /api/v2/workspaces
• ✅ GET /api/v2/tasks (correct, already exists)

The implementation uses the actual backend endpoints from file:codeframe/ui/routers/workspace_v2.py and file:codeframe/ui/routers/tasks_v2.py.

10. Testing Considerations

Create test files following existing patterns:

File: file:web-ui/__tests__/components/workspace/WorkspaceHeader.test.tsx (new file)

• Test initialization button visibility based on workspace existence
• Test button click triggers onInitialize callback
• Test loading state during initialization
• Test error message display

File: file:web-ui/__tests__/components/workspace/WorkspaceStatsCards.test.tsx (new file)

• Test rendering of all three cards
• Test task status badge colors match Nova palette
• Test empty states for missing data
• Test active runs link navigation

File: file:web-ui/__tests__/app/page.test.tsx (new file)

• Test SWR data fetching with MSW mocks
• Test initialization flow
• Test error states and retry
• Test responsive layout

Use test infrastructure (Jest, React Testing Library, MSW for API mocking)

11. Environment Configuration

File: file:web-ui/.env.example (new file)

Create environment template:

NEXT_PUBLIC_API_URL=http://localhost:8000

File: file:web-ui/.env.local (development)

Set local API URL for development

12. Build & Deployment Configuration

File: file:web-ui/next.config.js (new file)

Configure Next.js with:

• App Router enabled (default in Next.js 14)
• No special plugins needed
• Image optimization disabled (not needed for Phase 3)

File: file:web-ui/tailwind.config.ts (new file)

Use Shadcn/UI Nova template configuration

File: file:web-ui/postcss.config.js (new file)

Configure PostCSS with Tailwind and Autoprefixer

Component Hierarchy Diagram

graph TD
    A[RootLayout<br/>layout.tsx] --> B[Navigation Bar]
    A --> C[WorkspaceView<br/>page.tsx]
    
    C --> D[WorkspaceHeader]
    C --> E[WorkspaceStatsCards]
    C --> F[QuickActions]
    C --> G[RecentActivityFeed]
    
    D --> D1[RepoPathDisplay]
    D --> D2[InitializeWorkspaceButton]
    
    E --> E1[TechStackCard]
    E --> E2[TaskStatsCard]
    E --> E3[ActiveRunsCard]
    
    E2 --> E2A[Status Badges]
    
    F --> F1[PRD Link]
    F --> F2[Tasks Link]
    F --> F3[Review Link]
    
    G --> G1[ActivityItem[]]
    
    style A fill:#e3f2fd
    style C fill:#e3f2fd
    style D fill:#fff3e0
    style E fill:#fff3e0
    style F fill:#fff3e0
    style G fill:#fff3e0

Loading

Data Flow

sequenceDiagram
    participant User
    participant WorkspaceView
    participant SWR
    participant API
    participant Backend

    User->>WorkspaceView: Navigate to /
    WorkspaceView->>SWR: useSWR('/api/v2/workspaces/current')
    SWR->>API: GET /api/v2/workspaces/current
    API->>Backend: Request workspace info
    
    alt Workspace exists
        Backend-->>API: WorkspaceResponse
        API-->>SWR: Workspace data
        SWR-->>WorkspaceView: Render initialized view
        WorkspaceView->>SWR: useSWR('/api/v2/tasks')
        SWR->>API: GET /api/v2/tasks
        API->>Backend: Request task counts
        Backend-->>API: TaskListResponse with by_status
        API-->>SWR: Task counts
        SWR-->>WorkspaceView: Render stats cards
    else Workspace not found
        Backend-->>API: 404 or empty response
        API-->>SWR: Error/null
        SWR-->>WorkspaceView: Show init button
        User->>WorkspaceView: Click "Initialize Workspace"
        WorkspaceView->>API: POST /api/v2/workspaces
        API->>Backend: Create workspace
        Backend-->>API: WorkspaceResponse
        API-->>WorkspaceView: Success
        WorkspaceView->>SWR: mutate() to refresh
    end

Loading

File Structure Summary

web-ui/
├── src/
│   ├── app/
│   │   ├── layout.tsx                    (root layout with providers)
│   │   ├── page.tsx                      (workspace view - home)
│   │   └── globals.css                   (tailwind + global styles)
│   ├── components/
│   │   ├── workspace/
│   │   │   ├── WorkspaceHeader.tsx
│   │   │   ├── WorkspaceStatsCards.tsx
│   │   │   ├── QuickActions.tsx
│   │   │   └── RecentActivityFeed.tsx
│   │   └── layout/
│   │       └── RootLayout.tsx
│   ├── lib/
│   │   └── api.ts                        (API client)
│   └── types/
│       └── index.ts                      (TypeScript types)
├── __tests__/
│   ├── components/workspace/
│   │   ├── WorkspaceHeader.test.tsx
│   │   └── WorkspaceStatsCards.test.tsx
│   └── app/
│       └── page.test.tsx
├── package.json
├── tsconfig.json
├── next.config.js
├── tailwind.config.ts
├── postcss.config.js
├── jest.config.js
├── .env.example
└── README.md

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a legacy project-based architecture at the root route (`/`) showing a ProjectList component. Phase 3 introduces a workspace-based architecture using v2 API endpoints (`/api/v2/workspaces`, `/api/v2/tasks`). The frontend uses Next.js 14 App Router, Shadcn/UI Nova template, Hugeicons, and SWR for data fetching. The backend workspace API is implemented in `file:codeframe/ui/routers/workspace_v2.py` and tasks API in `file:codeframe/ui/routers/tasks_v2.py`. The Phase 3 architecture document defines a complete golden path UI with 6 core views. A brand new UI structure is required, separate from the legacy pages, to implement the Phase 3 vision.

## Approach

Create a brand new UI application structure alongside the legacy codebase. Establish a new Next.js app directory at `web-ui/` with a fresh component architecture following the Phase 3 specification. Build the Workspace View as the first Phase 3 view, implementing the component hierarchy: WorkspaceView → WorkspaceHeader, WorkspaceStatsCards, RecentActivityFeed. Use Shadcn/UI components (Card, Button, Badge) and Hugeicons for consistency with the Nova template. Implement workspace initialization flow with conditional rendering based on workspace existence. Fetch data using SWR with the v2 API endpoints, handling loading and error states gracefully. Follow the golden path philosophy by keeping the UI minimal and focused on essential workspace information.

## Implementation Steps

### 0. Project Structure Setup

**Create new web-ui directory structure:**

```
web-ui/
├── src/
│   ├── app/
│   │   ├── layout.tsx          (root layout with providers)
│   │   ├── page.tsx            (workspace view)
│   │   ├── globals.css         (tailwind + global styles)
│   │   └── (other views)       (prd, tasks, execution, blockers, review)
│   ├── components/
│   │   ├── workspace/          (workspace-specific components)
│   │   ├── shared/             (reusable components)
│   │   └── layout/             (sidebar, header, etc.)
│   ├── lib/
│   │   ├── api.ts              (API client)
│   │   └── hooks.ts            (custom hooks)
│   └── types/
│       └── index.ts            (TypeScript types)
├── package.json
├── tsconfig.json
├── next.config.js
├── tailwind.config.ts
├── postcss.config.js
└── jest.config.js
```

**File**: `file:web-ui/package.json` (new file)

Create package.json with dependencies:
- Next.js 14.1.0
- React 18.2.0
- Shadcn/UI components
- @hugeicons/react 0.3.0
- SWR 2.2.4
- Tailwind CSS 3.4.1
- TypeScript 5.3.3
- Testing libraries (Jest, React Testing Library, MSW)

**File**: `file:web-ui/tsconfig.json` (new file)

Configure TypeScript with path aliases (`@/*` → `./src/*`)

**File**: `file:web-ui/next.config.js` (new file)

Configure Next.js with App Router, no special plugins needed

**File**: `file:web-ui/tailwind.config.ts` (new file)

Use Shadcn/UI Nova template configuration with Tailwind CSS

**File**: `file:web-ui/src/app/layout.tsx` (new file)

Create root layout with:
- Metadata (title, description)
- Providers wrapper (SWR, error boundary)
- Global styles import
- Navigation sidebar (placeholder for Phase 3 sidebar)

### 1. API Client Setup

**File**: `file:web-ui/src/lib/api.ts` (new file)

Create workspace API client methods:

```typescript
import axios from 'axios';

const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000',
  withCredentials: true,
});

export const workspaceApi = {
  // Check if workspace exists at a path
  checkExists: (repoPath: string) => 
    api.get<{ exists: boolean; path: string; state_dir: string | null }>(
      '/api/v2/workspaces/exists', 
      { params: { repo_path: repoPath } }
    ),
  
  // Initialize workspace
  init: (repoPath: string, techStack?: string, detect?: boolean) =>
    api.post<WorkspaceResponse>('/api/v2/workspaces', {
      repo_path: repoPath,
      tech_stack: techStack,
      detect: detect ?? true
    }),
  
  // Get current workspace info
  getCurrent: (workspacePath?: string) =>
    api.get<WorkspaceResponse>('/api/v2/workspaces/current', {
      params: workspacePath ? { workspace_path: workspacePath } : {}
    })
};

export const tasksApi = {
  // Get all tasks with optional filtering
  getAll: (status?: string) =>
    api.get<TaskListResponse>('/api/v2/tasks', {
      params: status ? { status } : {}
    })
};

export default api;
```

**File**: `file:web-ui/src/types/index.ts` (new file)

Create TypeScript types for workspace and task responses:

```typescript
export interface WorkspaceResponse {
  id: string;
  repo_path: string;
  state_dir: string;
  tech_stack: string | null;
  created_at: string;
}

export interface TaskStatusCounts {
  BACKLOG: number;
  READY: number;
  IN_PROGRESS: number;
  DONE: number;
  BLOCKED: number;
  FAILED: number;
}

export interface Task {
  id: string;
  title: string;
  description: string;
  status: 'BACKLOG' | 'READY' | 'IN_PROGRESS' | 'DONE' | 'BLOCKED' | 'FAILED';
  effort?: number;
  dependencies?: string[];
  created_at: string;
  updated_at: string;
}

export interface TaskListResponse {
  tasks: Task[];
  by_status: TaskStatusCounts;
  total: number;
}

export interface ActivityItem {
  id: string;
  type: 'task_completed' | 'run_started' | 'blocker_raised' | 'workspace_initialized';
  timestamp: string;
  description: string;
  metadata?: Record<string, unknown>;
}
```

### 2. Workspace Header Component

**File**: `file:web-ui/src/components/workspace/WorkspaceHeader.tsx` (new file)

Create header component with repo path display and initialization button:

- Display repository path using `FolderIcon` from Hugeicons
- Show "Initialize Workspace" button if workspace doesn't exist
- Use Shadcn Button component with primary variant
- Handle initialization with loading state (disable button, show spinner)
- Display success/error messages using inline alerts
- Props: `workspace: WorkspaceResponse | null`, `isLoading: boolean`, `onInitialize: () => Promise<void>`
- Show workspace path in breadcrumb format: "CodeFRAME / ~/projects/my-app"

### 3. Workspace Stats Cards Component

**File**: `file:web-ui/src/components/workspace/WorkspaceStatsCards.tsx` (new file)

Create stats cards grid using Shadcn Card components:

**TechStackCard**:
- Icon: `Code2Icon` from Hugeicons
- Title: "Tech Stack"
- Content: Display detected tech stack or "Not detected" placeholder
- Use `text-muted-foreground` for empty state
- Props: `techStack: string | null`

**TaskStatsCard**:
- Icon: `ChecklistIcon` from Hugeicons  
- Title: "Tasks"
- Content: Display counts by status with colored badges
  - READY: `bg-blue-100 text-blue-900`
  - IN_PROGRESS: `bg-amber-100 text-amber-900`
  - DONE: `bg-green-100 text-green-900`
  - BLOCKED: `bg-red-100 text-red-900`
  - FAILED: `bg-red-200 text-red-900`
- Show total count prominently
- Use Shadcn Badge component for status indicators
- Props: `counts: TaskStatusCounts`

**ActiveRunsCard**:
- Icon: `PlayIcon` from Hugeicons
- Title: "Active Runs"
- Content: Display count of currently executing tasks
- Show "0" with muted styling when no active runs
- Add "View Execution" link if count > 0 (navigates to `/execution`)
- Props: `activeRunCount: number`

Layout: 3-column grid on desktop (`grid-cols-1 md:grid-cols-3`), responsive stacking on mobile

### 4. Recent Activity Feed Component

**File**: `file:web-ui/src/components/workspace/RecentActivityFeed.tsx` (new file)

Create activity timeline showing last 5 events:

- Use Shadcn Card component as container
- Title: "Recent Activity" with `HistoryIcon` from Hugeicons
- Display empty state if no activities: "No recent activity"
- Each ActivityItem shows:
  - Event type icon (task completed, run started, blocker raised, etc.)
  - Timestamp (relative format: "2 hours ago" using `date-fns`)
  - Description text
  - Optional link to related entity (task, run, blocker)
- Use vertical timeline layout with connecting lines
- Limit to 5 most recent items
- Props: `activities: ActivityItem[]`

**Note**: Since the backend doesn't have a dedicated activity endpoint yet, initially render with empty state and add TODO comment for future integration with event streaming.

### 5. Main Workspace View Page

**File**: `file:web-ui/src/app/page.tsx` (new file)

Create the Workspace View as the home/landing page:

**Data Fetching**:
- Use SWR to fetch workspace status from `GET /api/v2/workspaces/current`
- Use SWR to fetch task counts from `GET /api/v2/tasks` (parse `by_status` field)
- Handle workspace_path from query params or localStorage
- Implement fallback: if no workspace_path, show initialization prompt

**Initialization Flow**:
1. Check if workspace exists using `workspaceApi.checkExists()`
2. If not exists, show WorkspaceHeader with init button
3. On init button click, call `workspaceApi.init()` with auto-detect enabled
4. After successful init, mutate SWR cache to refresh data
5. Show initialized workspace with stats cards

**Layout Structure**:
```
<main className="min-h-screen bg-background">
  <div className="max-w-7xl mx-auto px-4 py-8">
    <WorkspaceHeader />
    {isInitialized && (
      <>
        <WorkspaceStatsCards />
        <QuickActions />
        <RecentActivityFeed />
      </>
    )}
  </div>
</main>
```

**Error Handling**:
- Show error boundary for critical failures
- Display inline error messages for API failures
- Provide retry buttons for failed operations

**Loading States**:
- Show skeleton loaders for stats cards while fetching
- Use Spinner component from Hugeicons
- Disable interactive elements during mutations

### 6. Quick Actions Component

**File**: `file:web-ui/src/components/workspace/QuickActions.tsx` (new file)

Create quick navigation links for golden path workflow:

**Location**: Below WorkspaceStatsCards, above RecentActivityFeed

Create a "Quick Actions" section with buttons:
- "View PRD" → navigates to `/prd` (use `FileTextIcon`)
- "Manage Tasks" → navigates to `/tasks` (use `ChecklistIcon`)
- "Review Changes" → navigates to `/review` (use `GitBranchIcon`)

Use Shadcn Button with `variant="outline"` for secondary actions
Layout: Horizontal flex row with gap, wrap on mobile
Props: None (static navigation)

### 7. Responsive Design

Ensure mobile-friendly layout:
- Stats cards: Stack vertically on mobile (`grid-cols-1 md:grid-cols-3`)
- Quick actions: Wrap buttons on small screens (`flex-wrap`)
- Activity feed: Full width on all screen sizes
- Use Tailwind responsive prefixes (`sm:`, `md:`, `lg:`)
- Test with viewport widths: 375px (mobile), 768px (tablet), 1024px (desktop)

### 8. Root Layout & Providers

**File**: `file:web-ui/src/app/layout.tsx` (new file)

Create root layout with:
- Metadata (title: "CodeFRAME", description)
- Providers wrapper (SWR configuration, error boundary)
- Global styles import (Tailwind CSS)
- Navigation sidebar placeholder (for Phase 3 sidebar implementation)
- Workspace path breadcrumb in header

**File**: `file:web-ui/src/components/layout/RootLayout.tsx` (new file)

Create layout wrapper component:
- Top navigation bar with CodeFRAME logo
- Workspace path breadcrumb
- Placeholder for sidebar (will be implemented in Phase 3 sidebar ticket)
- Main content area with children

### 9. API Endpoint Corrections

**Documentation Update**: Note that the ticket's API endpoint references should be corrected:

- ❌ `GET /api/v2/workspace/status` → ✅ `GET /api/v2/workspaces/current`
- ❌ `POST /api/v2/workspace/init` → ✅ `POST /api/v2/workspaces`
- ✅ `GET /api/v2/tasks` (correct, already exists)

The implementation uses the actual backend endpoints from `file:codeframe/ui/routers/workspace_v2.py` and `file:codeframe/ui/routers/tasks_v2.py`.

### 10. Testing Considerations

Create test files following existing patterns:

**File**: `file:web-ui/__tests__/components/workspace/WorkspaceHeader.test.tsx` (new file)
- Test initialization button visibility based on workspace existence
- Test button click triggers `onInitialize` callback
- Test loading state during initialization
- Test error message display

**File**: `file:web-ui/__tests__/components/workspace/WorkspaceStatsCards.test.tsx` (new file)
- Test rendering of all three cards
- Test task status badge colors match Nova palette
- Test empty states for missing data
- Test active runs link navigation

**File**: `file:web-ui/__tests__/app/page.test.tsx` (new file)
- Test SWR data fetching with MSW mocks
- Test initialization flow
- Test error states and retry
- Test responsive layout

Use test infrastructure (Jest, React Testing Library, MSW for API mocking)

### 11. Environment Configuration

**File**: `file:web-ui/.env.example` (new file)

Create environment template:
```
NEXT_PUBLIC_API_URL=http://localhost:8000
```

**File**: `file:web-ui/.env.local` (development)

Set local API URL for development

### 12. Build & Deployment Configuration

**File**: `file:web-ui/next.config.js` (new file)

Configure Next.js with:
- App Router enabled (default in Next.js 14)
- No special plugins needed
- Image optimization disabled (not needed for Phase 3)

**File**: `file:web-ui/tailwind.config.ts` (new file)

Use Shadcn/UI Nova template configuration

**File**: `file:web-ui/postcss.config.js` (new file)

Configure PostCSS with Tailwind and Autoprefixer

## Component Hierarchy Diagram

```mermaid
graph TD
    A[RootLayout<br/>layout.tsx] --> B[Navigation Bar]
    A --> C[WorkspaceView<br/>page.tsx]
    
    C --> D[WorkspaceHeader]
    C --> E[WorkspaceStatsCards]
    C --> F[QuickActions]
    C --> G[RecentActivityFeed]
    
    D --> D1[RepoPathDisplay]
    D --> D2[InitializeWorkspaceButton]
    
    E --> E1[TechStackCard]
    E --> E2[TaskStatsCard]
    E --> E3[ActiveRunsCard]
    
    E2 --> E2A[Status Badges]
    
    F --> F1[PRD Link]
    F --> F2[Tasks Link]
    F --> F3[Review Link]
    
    G --> G1[ActivityItem[]]
    
    style A fill:#e3f2fd
    style C fill:#e3f2fd
    style D fill:#fff3e0
    style E fill:#fff3e0
    style F fill:#fff3e0
    style G fill:#fff3e0
```

## Data Flow

```mermaid
sequenceDiagram
    participant User
    participant WorkspaceView
    participant SWR
    participant API
    participant Backend

    User->>WorkspaceView: Navigate to /
    WorkspaceView->>SWR: useSWR('/api/v2/workspaces/current')
    SWR->>API: GET /api/v2/workspaces/current
    API->>Backend: Request workspace info
    
    alt Workspace exists
        Backend-->>API: WorkspaceResponse
        API-->>SWR: Workspace data
        SWR-->>WorkspaceView: Render initialized view
        WorkspaceView->>SWR: useSWR('/api/v2/tasks')
        SWR->>API: GET /api/v2/tasks
        API->>Backend: Request task counts
        Backend-->>API: TaskListResponse with by_status
        API-->>SWR: Task counts
        SWR-->>WorkspaceView: Render stats cards
    else Workspace not found
        Backend-->>API: 404 or empty response
        API-->>SWR: Error/null
        SWR-->>WorkspaceView: Show init button
        User->>WorkspaceView: Click "Initialize Workspace"
        WorkspaceView->>API: POST /api/v2/workspaces
        API->>Backend: Create workspace
        Backend-->>API: WorkspaceResponse
        API-->>WorkspaceView: Success
        WorkspaceView->>SWR: mutate() to refresh
    end
```

## File Structure Summary

```
web-ui/
├── src/
│   ├── app/
│   │   ├── layout.tsx                    (root layout with providers)
│   │   ├── page.tsx                      (workspace view - home)
│   │   └── globals.css                   (tailwind + global styles)
│   ├── components/
│   │   ├── workspace/
│   │   │   ├── WorkspaceHeader.tsx
│   │   │   ├── WorkspaceStatsCards.tsx
│   │   │   ├── QuickActions.tsx
│   │   │   └── RecentActivityFeed.tsx
│   │   └── layout/
│   │       └── RootLayout.tsx
│   ├── lib/
│   │   └── api.ts                        (API client)
│   └── types/
│       └── index.ts                      (TypeScript types)
├── __tests__/
│   ├── components/workspace/
│   │   ├── WorkspaceHeader.test.tsx
│   │   └── WorkspaceStatsCards.test.tsx
│   └── app/
│       └── page.test.tsx
├── package.json
├── tsconfig.json
├── next.config.js
├── tailwind.config.ts
├── postcss.config.js
├── jest.config.js
├── .env.example
└── README.md
```

---

Execution Information

Branch: main
Commit: b252361