[P1] UX: Add global progress stepper showing 10-step journey position

[frankbria]

Problem

Users don't know where they are in the 10-step journey. No visual indicator shows progress through:

1. Create project → 2. Discovery → 3. PRD → 4. Tasks → 5. Development → 6. Review → 7. Approve → 8. Commit → 9. PR → 10. Merge

Current State

• Phase indicator exists but only shows current phase name
• No visual timeline or progress bar
• Users report confusion about "what happens next"

Required Implementation

New Component: JourneyProgressStepper

<JourneyProgressStepper 
  currentStep={5}  // Development
  completedSteps={[1,2,3,4]}
  blockedSteps={[]}  // Optional: show failures
/>

Visual Design

① ─── ② ─── ③ ─── ④ ─── ⑤ ─── ⑥ ─── ⑦ ─── ⑧ ─── ⑨ ─── ⑩
Create  Disc   PRD   Tasks  Dev   Review  OK   Commit  PR   Merge
  ✓      ✓     ✓      ✓    ●      ○      ○      ○     ○      ○

Placement

• Dashboard header (below project name)
• Always visible during project lifecycle
• Clickable steps to navigate (where applicable)

Step Mapping to Project State

Step	Condition
1. Create	Always complete if project exists
2. Discovery	phase === 'discovery' or complete
3. PRD	prd_content exists
4. Tasks	tasks.length > 0
5. Development	phase === 'development'
6. Review	tasks with quality_gate_status
7. Approve	tasks.approved > 0
8. Commit	commits.length > 0
9. PR	prs.length > 0
10. Merge	prs.merged.length > 0

Acceptance Criteria

• Stepper renders in Dashboard header
• Current step is highlighted
• Completed steps show checkmarks
• Tooltips explain each step
• Responsive on mobile (compact mode)

Committee Report Reference

5/11 expert agents specifically called out missing progress indication. UX/UI designer rated this as "Critical (Blocking UX Issue)".

[traycerai]

Plan

Observations

The codebase uses a 5-phase system (discovery, planning, active, review, complete) with a 15-step workflow tracked via workflow_step on tasks. The existing PhaseProgress component shows phase-level progress, while PhaseIndicator displays only the current phase name. The ticket's 10-step journey requires mapping to available project state data. Critical limitation: No commit/PR/merge tracking exists in the current data models—these steps will need to derive state from task completion and quality gate status until backend tracking is implemented.

Approach

Create a new JourneyProgressStepper component that visualizes the 10-step journey by intelligently mapping project phase, task status, PRD availability, and quality gate results to journey steps. Place it in the Dashboard header below the project name for persistent visibility. Use a horizontal stepper design with numbered circles, connecting lines, and step labels. Leverage Tailwind CSS for styling consistency and make it responsive with a compact mobile view. The component will compute step completion status from existing API data without requiring backend changes.

Implementation Steps

1. Create JourneyProgressStepper Component

File: file:web-ui/src/components/JourneyProgressStepper.tsx

Create a new React component that:

• Accepts props: projectPhase, prdContent, tasks, qualityGateStatus (from existing Dashboard data)
• Defines the 10-step journey mapping:
  • Step 1 (Create): Always complete if project exists
  • Step 2 (Discovery): Complete when phase !== 'discovery' or PRD exists
  • Step 3 (PRD): Complete when prdContent is not null/empty
  • Step 4 (Tasks): Complete when tasks.length > 0
  • Step 5 (Development): Complete when any task has status === 'in_progress' or status === 'completed'
  • Step 6 (Review): Complete when any task has quality gate status (check via quality gates API)
  • Step 7 (Approve): Complete when any task has status === 'completed' with passing quality gates
  • Step 8 (Commit): Derive from completed tasks (placeholder until git tracking added)
  • Step 9 (PR): Placeholder (requires backend PR tracking)
  • Step 10 (Merge): Placeholder (requires backend merge tracking)
• Compute currentStep as the highest incomplete step
• Compute completedSteps array from the mapping logic
• Render horizontal stepper with:
  • Numbered circles (①②③④⑤⑥⑦⑧⑨⑩) using Unicode or custom SVG
  • Connecting lines between steps (solid for completed, dashed for incomplete)
  • Step labels below circles (Create, Discovery, PRD, Tasks, Dev, Review, Approve, Commit, PR, Merge)
  • Visual states: completed (✓ checkmark, green), current (● dot, blue), pending (○ circle, gray)
  • Tooltips on hover explaining each step (use Radix UI Tooltip)
• Make responsive:
  • Desktop: Full horizontal layout with all labels
  • Tablet: Abbreviated labels (Disc, Dev, Rev, etc.)
  • Mobile: Compact view showing only current step number and total (e.g., "Step 5/10")

2. Integrate into Dashboard Header

File: file:web-ui/src/components/Dashboard.tsx

Modify the Dashboard component:

• Import JourneyProgressStepper
• Locate the header section (around lines 303-538 based on file summary)
• Add the stepper below the project name and above the existing PhaseProgress component
• Pass required props from existing Dashboard state:
  • projectPhase: Extract from projectStatus?.phase
  • prdContent: From prdData?.prd_content
  • tasks: From tasksData?.tasks or agent state tasks
  • qualityGateStatus: Fetch from quality gates API or derive from task data
• Wrap in a container with appropriate spacing (e.g., mb-4 margin)

3. Add Step Computation Utility

File: file:web-ui/src/lib/journeyStepUtils.ts

Create utility functions:

• computeJourneySteps(projectData): Takes project phase, PRD, tasks, quality gates and returns { currentStep, completedSteps, blockedSteps }
• getStepLabel(stepNumber): Returns full and abbreviated labels for each step
• getStepTooltip(stepNumber): Returns explanatory text for tooltips
• isStepComplete(stepNumber, projectData): Boolean check for step completion
• Export step constants: JOURNEY_STEPS array with metadata (number, label, shortLabel, description)

4. Style the Stepper Component

Use Tailwind CSS classes:

• Container: flex items-center justify-between w-full px-4 py-3 bg-card rounded-lg border border-border
• Step circles: flex items-center justify-center w-8 h-8 rounded-full border-2 transition-colors
  • Completed: bg-green-500 border-green-500 text-white
  • Current: bg-primary border-primary text-primary-foreground
  • Pending: bg-muted border-border text-muted-foreground
• Connecting lines: flex-1 h-0.5 mx-2
  • Completed: bg-green-500
  • Pending: bg-border
• Labels: text-xs text-center mt-1 text-muted-foreground
• Responsive breakpoints: Use hidden md:block and block md:hidden for mobile/desktop variants

5. Add Tooltips for Step Explanations

File: file:web-ui/src/components/JourneyProgressStepper.tsx

Integrate Radix UI Tooltip (already used in codebase):

• Import from @radix-ui/react-tooltip or existing UI components
• Wrap each step circle in <Tooltip> component
• Tooltip content should explain:
  • What the step represents
  • Current status (completed/in progress/pending)
  • What triggers completion
• Example: "Step 6: Review - Run quality gates on completed tasks. Status: Pending"

6. Handle Click Navigation (Optional Enhancement)

Add click handlers to completed steps:

• Steps 1-4: Navigate to relevant Dashboard tab (Overview, Tasks)
• Step 3 (PRD): Open PRD modal (already exists in Dashboard)
• Step 6-7 (Review/Approve): Navigate to Quality Gates tab
• Disabled state for incomplete steps (cursor-not-allowed)

7. Add Unit Tests

File: file:web-ui/__tests__/components/JourneyProgressStepper.test.tsx

Test cases:

• Renders all 10 steps correctly
• Computes current step based on project state
• Shows checkmarks for completed steps
• Shows current step indicator
• Handles edge cases (no tasks, no PRD, etc.)
• Responsive behavior (desktop vs mobile)
• Tooltip content displays correctly

File: file:web-ui/__tests__/lib/journeyStepUtils.test.ts

Test utility functions:

• computeJourneySteps with various project states
• Step completion logic for each of the 10 steps
• Edge cases (null data, empty arrays)

8. Update Type Definitions

File: file:web-ui/src/types/index.ts or new file:web-ui/src/types/journey.ts

Add TypeScript interfaces:

export interface JourneyStep {
  number: number;
  label: string;
  shortLabel: string;
  description: string;
  isComplete: boolean;
  isCurrent: boolean;
  isBlocked: boolean;
}

export interface JourneyProgressData {
  currentStep: number;
  completedSteps: number[];
  blockedSteps: number[];
  steps: JourneyStep[];
}

9. Backend Enhancement Recommendations (Future Work)

Document in implementation notes that Steps 8-10 require backend support:

• Add commits table to track git commits per task
• Add pull_requests table to track PR creation and status
• Add merged_at timestamp to track merge completion
• Expose via API endpoints: /api/projects/{id}/commits, /api/projects/{id}/prs
• Update project status API to include commit/PR counts

10. Accessibility Enhancements

Ensure WCAG compliance:

• Add role="progressbar" to stepper container
• Add aria-label="Project journey progress: Step X of 10"
• Add aria-valuenow, aria-valuemin, aria-valuemax attributes
• Ensure keyboard navigation works (Tab through steps)
• Add focus indicators for keyboard users
• Ensure color contrast meets WCAG AA standards (use existing Tailwind theme colors)

Visual Design Reference

graph LR
    A[① Create<br/>✓] -->|completed| B[② Discovery<br/>✓]
    B -->|completed| C[③ PRD<br/>✓]
    C -->|completed| D[④ Tasks<br/>✓]
    D -->|completed| E[⑤ Dev<br/>●]
    E -.->|pending| F[⑥ Review<br/>○]
    F -.->|pending| G[⑦ Approve<br/>○]
    G -.->|pending| H[⑧ Commit<br/>○]
    H -.->|pending| I[⑨ PR<br/>○]
    I -.->|pending| J[⑩ Merge<br/>○]
    
    style A fill:#22c55e,stroke:#16a34a,color:#fff
    style B fill:#22c55e,stroke:#16a34a,color:#fff
    style C fill:#22c55e,stroke:#16a34a,color:#fff
    style D fill:#22c55e,stroke:#16a34a,color:#fff
    style E fill:#3b82f6,stroke:#2563eb,color:#fff
    style F fill:#e5e7eb,stroke:#9ca3af,color:#6b7280
    style G fill:#e5e7eb,stroke:#9ca3af,color:#6b7280
    style H fill:#e5e7eb,stroke:#9ca3af,color:#6b7280
    style I fill:#e5e7eb,stroke:#9ca3af,color:#6b7280
    style J fill:#e5e7eb,stroke:#9ca3af,color:#6b7280

Loading

Step-to-State Mapping Table

Step	Label	Completion Condition	Data Source
1	Create	Project exists	Always true in Dashboard
2	Discovery	phase !== 'discovery' OR PRD exists	projectStatus.phase, prdData
3	PRD	prd_content is not null/empty	prdData.prd_content
4	Tasks	tasks.length > 0	tasksData.tasks
5	Development	Any task status === 'in_progress' OR 'completed'	tasksData.tasks[].status
6	Review	Any task has quality gate status	Quality Gates API
7	Approve	Any task status === 'completed' with passing gates	tasksData.tasks[] + Quality Gates
8	Commit	Derive from completed tasks (placeholder)	Future: Git commits API
9	PR	Placeholder (requires backend)	Future: PRs API
10	Merge	Placeholder (requires backend)	Future: PRs API with merged_at

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase uses a **5-phase system** (discovery, planning, active, review, complete) with a 15-step workflow tracked via `workflow_step` on tasks. The existing `PhaseProgress` component shows phase-level progress, while `PhaseIndicator` displays only the current phase name. The ticket's 10-step journey requires mapping to available project state data. **Critical limitation**: No commit/PR/merge tracking exists in the current data models—these steps will need to derive state from task completion and quality gate status until backend tracking is implemented.

## Approach

Create a new `JourneyProgressStepper` component that visualizes the 10-step journey by intelligently mapping project phase, task status, PRD availability, and quality gate results to journey steps. Place it in the Dashboard header below the project name for persistent visibility. Use a horizontal stepper design with numbered circles, connecting lines, and step labels. Leverage Tailwind CSS for styling consistency and make it responsive with a compact mobile view. The component will compute step completion status from existing API data without requiring backend changes.

## Implementation Steps

### 1. Create JourneyProgressStepper Component

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

Create a new React component that:
- Accepts props: `projectPhase`, `prdContent`, `tasks`, `qualityGateStatus` (from existing Dashboard data)
- Defines the 10-step journey mapping:
  - **Step 1 (Create)**: Always complete if project exists
  - **Step 2 (Discovery)**: Complete when `phase !== 'discovery'` or PRD exists
  - **Step 3 (PRD)**: Complete when `prdContent` is not null/empty
  - **Step 4 (Tasks)**: Complete when `tasks.length > 0`
  - **Step 5 (Development)**: Complete when any task has `status === 'in_progress'` or `status === 'completed'`
  - **Step 6 (Review)**: Complete when any task has quality gate status (check via quality gates API)
  - **Step 7 (Approve)**: Complete when any task has `status === 'completed'` with passing quality gates
  - **Step 8 (Commit)**: Derive from completed tasks (placeholder until git tracking added)
  - **Step 9 (PR)**: Placeholder (requires backend PR tracking)
  - **Step 10 (Merge)**: Placeholder (requires backend merge tracking)
- Compute `currentStep` as the highest incomplete step
- Compute `completedSteps` array from the mapping logic
- Render horizontal stepper with:
  - Numbered circles (①②③④⑤⑥⑦⑧⑨⑩) using Unicode or custom SVG
  - Connecting lines between steps (solid for completed, dashed for incomplete)
  - Step labels below circles (Create, Discovery, PRD, Tasks, Dev, Review, Approve, Commit, PR, Merge)
  - Visual states: completed (✓ checkmark, green), current (● dot, blue), pending (○ circle, gray)
  - Tooltips on hover explaining each step (use Radix UI Tooltip)
- Make responsive:
  - Desktop: Full horizontal layout with all labels
  - Tablet: Abbreviated labels (Disc, Dev, Rev, etc.)
  - Mobile: Compact view showing only current step number and total (e.g., "Step 5/10")

### 2. Integrate into Dashboard Header

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

Modify the Dashboard component:
- Import `JourneyProgressStepper`
- Locate the header section (around lines 303-538 based on file summary)
- Add the stepper below the project name and above the existing `PhaseProgress` component
- Pass required props from existing Dashboard state:
  - `projectPhase`: Extract from `projectStatus?.phase`
  - `prdContent`: From `prdData?.prd_content`
  - `tasks`: From `tasksData?.tasks` or agent state tasks
  - `qualityGateStatus`: Fetch from quality gates API or derive from task data
- Wrap in a container with appropriate spacing (e.g., `mb-4` margin)

### 3. Add Step Computation Utility

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

Create utility functions:
- `computeJourneySteps(projectData)`: Takes project phase, PRD, tasks, quality gates and returns `{ currentStep, completedSteps, blockedSteps }`
- `getStepLabel(stepNumber)`: Returns full and abbreviated labels for each step
- `getStepTooltip(stepNumber)`: Returns explanatory text for tooltips
- `isStepComplete(stepNumber, projectData)`: Boolean check for step completion
- Export step constants: `JOURNEY_STEPS` array with metadata (number, label, shortLabel, description)

### 4. Style the Stepper Component

Use Tailwind CSS classes:
- Container: `flex items-center justify-between w-full px-4 py-3 bg-card rounded-lg border border-border`
- Step circles: `flex items-center justify-center w-8 h-8 rounded-full border-2 transition-colors`
  - Completed: `bg-green-500 border-green-500 text-white`
  - Current: `bg-primary border-primary text-primary-foreground`
  - Pending: `bg-muted border-border text-muted-foreground`
- Connecting lines: `flex-1 h-0.5 mx-2`
  - Completed: `bg-green-500`
  - Pending: `bg-border`
- Labels: `text-xs text-center mt-1 text-muted-foreground`
- Responsive breakpoints: Use `hidden md:block` and `block md:hidden` for mobile/desktop variants

### 5. Add Tooltips for Step Explanations

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

Integrate Radix UI Tooltip (already used in codebase):
- Import from `@radix-ui/react-tooltip` or existing UI components
- Wrap each step circle in `<Tooltip>` component
- Tooltip content should explain:
  - What the step represents
  - Current status (completed/in progress/pending)
  - What triggers completion
- Example: "Step 6: Review - Run quality gates on completed tasks. Status: Pending"

### 6. Handle Click Navigation (Optional Enhancement)

Add click handlers to completed steps:
- Steps 1-4: Navigate to relevant Dashboard tab (Overview, Tasks)
- Step 3 (PRD): Open PRD modal (already exists in Dashboard)
- Step 6-7 (Review/Approve): Navigate to Quality Gates tab
- Disabled state for incomplete steps (cursor-not-allowed)

### 7. Add Unit Tests

**File:** `file:web-ui/__tests__/components/JourneyProgressStepper.test.tsx`

Test cases:
- Renders all 10 steps correctly
- Computes current step based on project state
- Shows checkmarks for completed steps
- Shows current step indicator
- Handles edge cases (no tasks, no PRD, etc.)
- Responsive behavior (desktop vs mobile)
- Tooltip content displays correctly

**File:** `file:web-ui/__tests__/lib/journeyStepUtils.test.ts`

Test utility functions:
- `computeJourneySteps` with various project states
- Step completion logic for each of the 10 steps
- Edge cases (null data, empty arrays)

### 8. Update Type Definitions

**File:** `file:web-ui/src/types/index.ts` or new `file:web-ui/src/types/journey.ts`

Add TypeScript interfaces:
```typescript
export interface JourneyStep {
  number: number;
  label: string;
  shortLabel: string;
  description: string;
  isComplete: boolean;
  isCurrent: boolean;
  isBlocked: boolean;
}

export interface JourneyProgressData {
  currentStep: number;
  completedSteps: number[];
  blockedSteps: number[];
  steps: JourneyStep[];
}
```

### 9. Backend Enhancement Recommendations (Future Work)

Document in implementation notes that Steps 8-10 require backend support:
- Add `commits` table to track git commits per task
- Add `pull_requests` table to track PR creation and status
- Add `merged_at` timestamp to track merge completion
- Expose via API endpoints: `/api/projects/{id}/commits`, `/api/projects/{id}/prs`
- Update project status API to include commit/PR counts

### 10. Accessibility Enhancements

Ensure WCAG compliance:
- Add `role="progressbar"` to stepper container
- Add `aria-label="Project journey progress: Step X of 10"`
- Add `aria-valuenow`, `aria-valuemin`, `aria-valuemax` attributes
- Ensure keyboard navigation works (Tab through steps)
- Add focus indicators for keyboard users
- Ensure color contrast meets WCAG AA standards (use existing Tailwind theme colors)

## Visual Design Reference

```mermaid
graph LR
    A[① Create<br/>✓] -->|completed| B[② Discovery<br/>✓]
    B -->|completed| C[③ PRD<br/>✓]
    C -->|completed| D[④ Tasks<br/>✓]
    D -->|completed| E[⑤ Dev<br/>●]
    E -.->|pending| F[⑥ Review<br/>○]
    F -.->|pending| G[⑦ Approve<br/>○]
    G -.->|pending| H[⑧ Commit<br/>○]
    H -.->|pending| I[⑨ PR<br/>○]
    I -.->|pending| J[⑩ Merge<br/>○]
    
    style A fill:#22c55e,stroke:#16a34a,color:#fff
    style B fill:#22c55e,stroke:#16a34a,color:#fff
    style C fill:#22c55e,stroke:#16a34a,color:#fff
    style D fill:#22c55e,stroke:#16a34a,color:#fff
    style E fill:#3b82f6,stroke:#2563eb,color:#fff
    style F fill:#e5e7eb,stroke:#9ca3af,color:#6b7280
    style G fill:#e5e7eb,stroke:#9ca3af,color:#6b7280
    style H fill:#e5e7eb,stroke:#9ca3af,color:#6b7280
    style I fill:#e5e7eb,stroke:#9ca3af,color:#6b7280
    style J fill:#e5e7eb,stroke:#9ca3af,color:#6b7280
```

## Step-to-State Mapping Table

| Step | Label | Completion Condition | Data Source |
|------|-------|---------------------|-------------|
| 1 | Create | Project exists | Always true in Dashboard |
| 2 | Discovery | `phase !== 'discovery'` OR PRD exists | `projectStatus.phase`, `prdData` |
| 3 | PRD | `prd_content` is not null/empty | `prdData.prd_content` |
| 4 | Tasks | `tasks.length > 0` | `tasksData.tasks` |
| 5 | Development | Any task `status === 'in_progress'` OR `'completed'` | `tasksData.tasks[].status` |
| 6 | Review | Any task has quality gate status | Quality Gates API |
| 7 | Approve | Any task `status === 'completed'` with passing gates | `tasksData.tasks[]` + Quality Gates |
| 8 | Commit | Derive from completed tasks (placeholder) | Future: Git commits API |
| 9 | PR | Placeholder (requires backend) | Future: PRs API |
| 10 | Merge | Placeholder (requires backend) | Future: PRs API with `merged_at` |

---

Execution Information

Branch: main
Commit: a107395

---

💡 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.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#194 - Fix PRD generation progress tracking UI [merged]
#211 - feat(dashboard): Add PhaseProgress component for phase visualization [merged]
#213 - feat(planning): Add Generate Task Breakdown button to DiscoveryProgress [merged]
#214 - feat(planning): Add TaskReview component for task approval workflow [merged]
#215 - feat(dashboard): Add phase-aware task view integration (#16-6) [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[frankbria]

Closing as part of v2 roadmap cleanup. This v1-specific issue is retained with the v1-legacy label as reference material for Phase 3 (Web UI rebuild). See the v2 strategic roadmap for current priorities.