Created: 2026-02-03 Status: Approved design for golden path UI
This document defines the information architecture for the CodeFRAME web UI. The UI follows the "golden path" philosophy - we build only what's necessary for the core workflow, nothing more.
Key Constraints:
- CLI is fully functional and production-ready (Phase 1 complete)
- REST API with SSE streaming is complete (Phase 2 complete)
- UI should consume existing API, not drive new features
- Tech stack: Next.js App Router, Shadcn/UI + Tailwind (Nova template), Hugeicons
Purpose: Initialize and overview the current workspace state.
Key Actions:
- Initialize workspace (one-time setup per repo)
- View workspace metadata (tech stack, git status)
- Quick access to PRD, tasks, and active runs
Data Displayed:
- Workspace path and initialization status
- Detected tech stack configuration
- Quick stats: PRD count, task counts by status, active runs
- Recent activity timeline (last 5 events)
Purpose: Create, view, and iterate on Product Requirements Documents.
Key Actions:
- Upload/paste PRD markdown
- Start discovery session (Socratic AI conversation)
- Edit PRD content
- Generate tasks from PRD
Data Displayed:
- PRD content (markdown rendered)
- PRD metadata (version, created date, file path)
- Discovery session transcript (if applicable)
- Associated tasks count and status breakdown
Purpose: Visualize and manage task lifecycle from backlog to completion.
Key Actions:
- View tasks grouped by status (BACKLOG, READY, IN_PROGRESS, DONE, BLOCKED, FAILED)
- Filter/search tasks
- Execute single task
- Start batch execution
- View task details
- Mark tasks as READY manually
Data Displayed:
- Kanban-style columns (or simple list grouped by status)
- Per-task cards showing: title, description snippet, status, dependencies, effort estimate
- Batch execution controls (strategy selector, retry config)
- Task dependency indicators (visual cues for blocked/blocking relationships)
Purpose: Real-time observation of AI agent task execution.
Key Actions:
- View streaming output (planning, file changes, shell commands, verification)
- Pause/stop execution
- Answer blockers inline
- Review generated changes (file diffs)
Data Displayed:
- Task being executed (title, description)
- Agent state (PLANNING, EXECUTING, BLOCKED, COMPLETED, FAILED)
- Live event stream with timestamps
- File changes preview (collapsible sections)
- Verification gate results (ruff, pytest)
- Blocker questions (if raised)
Purpose: Respond to agent questions and unblock stuck tasks.
Key Actions:
- View open blockers
- Provide text answer to blocker
- Mark blocker as resolved
- Resume blocked task
Data Displayed:
- List of open blockers (task context, blocker question, timestamp)
- Blocker detail (full context, attempted fixes, agent's question)
- Answer input form
- History of resolved blockers (optional, low priority)
Purpose: Inspect changes and commit to git with confidence.
Key Actions:
- View unified diff of all changes
- Run quality checks (lint, tests)
- Export patch file
- Commit with generated message
- Create GitHub PR
Data Displayed:
- File tree with changed files highlighted
- Unified diff viewer (syntax highlighted)
- Quality gate results (pass/fail badges)
- Commit message suggestion (from AI)
- PR creation form (title, description)
Persistent left sidebar with icon + label navigation:
- Workspace (home icon)
- PRD (document icon)
- Tasks (checklist icon)
- Execution (play/monitor icon) - only visible when runs are active
- Blockers (alert icon) - badge count for open blockers
- Review (git branch icon)
- PROOF9 (checkmark icon)
- Sessions (command-line icon) - badge count for active sessions
Sidebar action button: A "Capture Glitch" button (Add01Icon) is always visible at the bottom of the sidebar. Clicking it opens CaptureGlitchModal without navigating away from the current page. This is the primary entry point for the glitch capture closed loop from anywhere in the app.
- Workspace breadcrumb at top: shows current repo path, links to workspace root
- Task detail modal opens from Task Board (overlay, not new view)
- Blocker answer modal opens from Execution Monitor or Blocker view (inline expansion preferred)
Workspace → PRD → Tasks → Execution Monitor → Blockers (if needed) → Review & Commit
↓ ↓
(Generate Tasks) (Create PR)
/ → Workspace View
/prd → PRD View
/prd/discovery → PRD Discovery Session (sub-view)
/tasks → Task Board View
/tasks/:id → Task Detail (modal overlay)
/execution → Execution Monitor (auto-navigates when run starts)
/execution/:run_id → Specific run monitoring
/blockers → Blocker Resolution View
/review → Review & Commit View
WorkspaceView
├── WorkspaceHeader
│ ├── RepoPathDisplay
│ └── InitializeWorkspaceButton (if not initialized)
├── WorkspaceStatsCards
│ ├── TechStackCard
│ ├── TaskStatsCard (READY, IN_PROGRESS, DONE counts)
│ └── ActiveRunsCard
└── RecentActivityFeed
└── ActivityItem[] (event type, timestamp, description)
Modals: None Panels: None (single-column layout)
PRDView
├── PRDHeader
│ ├── PRDTitle (editable inline)
│ ├── PRDActions
│ │ ├── UploadPRDButton
│ │ ├── StartDiscoveryButton
│ │ └── GenerateTasksButton
│ └── PRDMetadata (version, file path)
├── PRDContent (two-column when discovery active)
│ ├── MarkdownEditor (left, or full-width when no discovery)
│ └── DiscoveryPanel (right, collapsible)
│ ├── DiscoveryTranscript (chat-style messages)
│ └── DiscoveryInput (text input + send button)
└── AssociatedTasksSummary
└── TaskCountByStatus (compact badges)
Modals:
UploadPRDModal(file picker or paste markdown)
Panels:
DiscoveryPanel(slides in from right when session starts)
TaskBoardView
├── TaskBoardHeader
│ ├── TaskFilters (status, search bar)
│ └── BatchActions
│ ├── SelectTasksMode (checkbox selection)
│ ├── BatchStrategySelector (serial/parallel/auto)
│ └── ExecuteBatchButton
├── TaskBoardContent (Kanban columns or grouped list)
│ ├── TaskColumn (status: BACKLOG)
│ │ └── TaskCard[]
│ ├── TaskColumn (status: READY)
│ ├── TaskColumn (status: IN_PROGRESS)
│ ├── TaskColumn (status: BLOCKED)
│ ├── TaskColumn (status: FAILED)
│ └── TaskColumn (status: DONE)
└── TaskQuickActions (floating action button)
└── CreateTaskManuallyButton (low priority)
TaskCard Component:
TaskCard
├── TaskTitle
├── TaskDescriptionSnippet (truncated)
├── TaskMetadata (effort, dependencies badge)
├── TaskStatusBadge
└── TaskActions
├── ViewDetailsButton
├── ExecuteButton (if READY)
└── MarkReadyButton (if BACKLOG)
Modals:
TaskDetailModal(full description, dependencies, execution history, edit controls)
Panels: None
ExecutionMonitorView
├── ExecutionHeader
│ ├── CurrentTaskTitle
│ ├── AgentStateBadge (PLANNING, EXECUTING, BLOCKED, etc.)
│ └── ExecutionControls
│ ├── PauseButton
│ └── StopButton
├── EventStream (main content, scrollable)
│ ├── EventItem[] (timestamp, event type, content)
│ │ ├── PlanningEvent (displays plan steps)
│ │ ├── FileChangeEvent (collapsible diff preview)
│ │ ├── ShellCommandEvent (command + output)
│ │ ├── VerificationEvent (gate results, pass/fail)
│ │ └── BlockerEvent (blocker question, inline answer form)
│ └── AutoScrollToggle (stick to bottom or allow manual scroll)
├── ProgressIndicator (top or sidebar)
│ ├── CurrentStepDisplay (e.g., "Step 3 of 7: Running pytest")
│ └── ProgressBar
└── ChangesSidebar (collapsible right panel)
├── ChangedFilesList (tree view)
└── FileDiffPreview (click to expand in sidebar)
Modals:
BlockerAnswerModal(or inline expansion in EventStream - prefer inline)
Panels:
ChangesSidebar(right-side collapsible, shows file diffs)
BlockerResolutionView
├── BlockerList
│ └── BlockerCard[]
│ ├── TaskContext (task title, description)
│ ├── BlockerQuestion (agent's question, highlighted)
│ ├── BlockerMetadata (timestamp, attempts count)
│ ├── AnswerForm (text area + submit button)
│ └── ResolveButton (marks resolved, resumes task)
└── ResolvedBlockersAccordion (collapsed by default)
└── ResolvedBlockerItem[]
Modals: None (inline answer forms) Panels: None
ReviewCommitView
├── ReviewHeader
│ ├── ChangeSummary (X files changed, Y insertions, Z deletions)
│ └── QualityGateResults
│ ├── GateBadge (ruff: passed)
│ └── GateBadge (pytest: 12/12 passed)
├── FileTreePanel (left sidebar, 25% width)
│ └── FileTree (changed files, click to view diff)
├── DiffViewer (main content, 75% width)
│ ├── UnifiedDiff (syntax highlighted)
│ └── DiffNavigation (prev/next file buttons)
└── CommitPanel (bottom or right panel)
├── CommitMessageSuggestion (AI-generated, editable)
├── CommitButton
└── PRCreationToggle
└── PRForm (title, description, auto-populated)
Modals:
ExportPatchModal(displays patch content, copy button)PRCreatedModal(success message + PR URL)
Panels:
FileTreePanel(left, persistent)CommitPanel(bottom or right, collapsible)
Purpose: Trigger gate runs, inspect per-gate evidence, and review run history.
Key Actions:
- Run quality gates via
[Run Gates]button (callsPOST /api/v2/proof/run) - View live gate progress (pending → running → passed/failed) per gate
- Inspect per-gate evidence artifacts (test output, coverage report, etc.)
- Browse run history for the last 5 gate runs
- Waive requirements with a reason and optional expiry
Data Displayed:
- Requirements table with status badges (open / satisfied / waived)
- Gate run progress (per-gate status, triggered after [Run Gates] click)
- Evidence artifacts for each gate in a run
- Run history panel with outcome and duration
Component Hierarchy:
ProofPage (/proof)
├── ProofHeader
│ ├── RunGatesButton → POST /api/v2/proof/run
│ └── ProofStatusSummary (open / satisfied / waived counts)
├── RequirementsTable
│ └── RequirementRow[]
│ ├── StatusBadge
│ └── WaiveButton
├── GateEvidencePanel ← new (Phase 3.5B)
│ ├── GateProgressRow[] (pending → running → passed/failed)
│ └── EvidenceArtifactDisplay (artifact text, scrollable)
└── RunHistoryPanel ← new (Phase 3.5B)
└── RunSummaryRow[] (run_id, started_at, duration, overall_passed)
└── (click → loads GateEvidencePanel for that run)
ProofRequirementPage (/proof/[req_id])
├── RequirementHeader
│ ├── Title, severity badge, ProofStatusBadge
│ ├── MarkdownDescription (ReactMarkdown, images disallowed)
│ ├── MetadataRow (created_at, source, source_issue, created_by, waiver expiry)
│ └── ScopeChips (files, routes, components, APIs, tags from ProofScope)
├── ObligationsTable ← new (Phase 3.5C)
│ └── ObligationRow[] (gate name, Latest Run pass/fail badge, link to evidence)
│ └── Latest Run column: shows most-recent run result per gate
├── EvidenceHistory
│ ├── FilterBar (gate select, result select, search input, Reset Filters)
│ ├── EvidenceTable (sortable: gate, result, run_id, timestamp, artifact)
│ │ └── EvidenceRow[] (click run_id → focusRun filter)
│ └── EmptyState CTA: "Capture a Glitch" link when no evidence exists
├── GateEvidencePanel (loads artifact content for latest run)
└── WaiveDialog (modal, opens via Waive button in header)
API Endpoints Used:
POST /api/v2/proof/run— trigger gate runGET /api/v2/proof/runs— list run history (limit=5)GET /api/v2/proof/runs/{run_id}/evidence— per-gate evidence with artifact textGET /api/v2/proof/requirements— list requirementsGET /api/v2/proof/status— aggregated counts
Modals: None Panels:
GateEvidencePanel(replaces main content area after run starts)RunHistoryPanel(bottom panel, always visible on/proofpage)
Connection Management:
- Open SSE connection when navigating to Execution Monitor View
- Subscribe to
/api/v2/tasks/{task_id}/streamendpoint - Maintain connection until run completes or user navigates away
- Automatic reconnection with exponential backoff on disconnect
Event Stream Display:
┌─────────────────────────────────────────────────────┐
│ 10:23:45 [PLANNING] │
│ • Analyzing task requirements... │
│ • Generated 5-step plan │
│ │
│ 10:23:47 [EXECUTING] Step 1/5 │
│ Creating file: src/auth/middleware.py │
│ [View Diff ▼] │
│ │
│ 10:23:48 [VERIFICATION] │
│ ✓ ruff check: passed │
│ │
│ 10:23:50 [EXECUTING] Step 2/5 │
│ Running: pytest tests/auth/ │
│ stdout: ===== test session starts ===== │
│ stdout: collected 3 items │
│ ✗ FAILED tests/auth/test_middleware.py::test_1 │
│ │
│ 10:23:52 [SELF_CORRECTING] │
│ Attempting fix (1/3)... │
│ • Detected ImportError for Optional │
│ • Applying quick fix: add missing import │
│ │
│ 10:23:54 [VERIFICATION] │
│ ✓ pytest: 3/3 passed │
│ ✓ All gates passed │
│ │
│ 10:23:55 [COMPLETED] │
│ Task completed successfully │
└─────────────────────────────────────────────────────┘
Event Type Styling:
| Event | Badge Color | Details |
|---|---|---|
| PLANNING | Blue | Indented bullet list |
| EXECUTING | Green | Step counter (X/Y), collapsible details |
| VERIFICATION | Orange → Green/Red | Checkmark when passed, X when failed |
| SELF_CORRECTING | Yellow | Shows attempt count |
| BLOCKED | Red | Interrupt pattern with inline form |
| COMPLETED | Green | Success icon |
| FAILED | Red | Error icon |
Interrupt Pattern for Blockers:
┌─────────────────────────────────────────────────────┐
│ 10:24:10 [BLOCKED] 🚨 │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Agent needs your help: │ │
│ │ │ │
│ │ "Should I use JWT or session-based auth for │ │
│ │ the API? The PRD mentions 'secure auth' but │ │
│ │ doesn't specify implementation." │ │
│ │ │ │
│ │ [Text input area] │ │
│ │ │ │
│ │ [Answer Blocker] [View Full Context] │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ Execution paused - waiting for response... │
└─────────────────────────────────────────────────────┘
Auto-scroll Behavior:
- Default: stick to bottom (new events auto-scroll into view)
- User scrolls up: pause auto-scroll, show "New events ↓" button at bottom
- Click button or scroll to bottom: re-enable auto-scroll
Pattern: Chat-style interface with AI leading questions.
Flow:
- User clicks "Start Discovery Session" button
- Discovery panel slides in from right (or expands below PRD editor)
- AI sends first message: "What problem does this project solve?"
- User types answer in chat input
- AI acknowledges, asks follow-up: "Who are the primary users?"
- Conversation continues (multi-turn, 5-10 questions typical)
- AI signals completion: "I have enough information to generate a PRD. Review below."
- AI-generated PRD appears in markdown editor (left pane)
- User can edit, then click "Generate Tasks"
Key UX Details:
- Clear AI branding: Avatar or badge for AI messages
- Thinking indicator: Animated dots while AI generates next question
- Conversation persistence: Session saved, can resume later
- Skip option: "I'll write the PRD manually" button to close discovery
- Edit-as-you-go: User can edit generated PRD before finalizing
Pattern: Real-time streaming with progressive disclosure.
Flow:
- User clicks "Execute" on a READY task
- Auto-navigate to Execution Monitor View
- SSE connection opens, events stream in
- Collapsible sections for verbose output (file diffs, shell output)
- Critical events (blockers, failures) interrupt with highlighted banner
- On completion, show success summary + "View Changes" button (navigates to Review)
Key UX Details:
- Visual hierarchy: Critical events (BLOCKED, FAILED) use color + size to grab attention
- Diff previews: Inline, collapsible, syntax-highlighted
- Command output: Monospace font, collapsible, scrollable
- Pause/stop controls: Always visible at top, confirm before stopping
Pattern: Inline expansion with context visibility.
Flow:
- Agent raises blocker during execution
- Interrupt pattern in Execution Monitor (highlighted blocker event)
- User types answer in inline form
- Click "Answer Blocker" → sends answer to API
- Execution auto-resumes after answer submitted
Key UX Details:
- Context visibility: Show task title, description, and agent's attempted fixes
- Guidance questions: AI can suggest what information it needs
- No dead ends: Option to skip/cancel blocker (marks task as BLOCKED)
- Notification badge: Blocker count on sidebar icon
Pattern: Multi-task progress dashboard with strategy selector.
Batch Execution Monitor Layout:
┌─────────────────────────────────────────────────────┐
│ Batch Execution (5 tasks) │
│ Strategy: Parallel (max 3) │
│ │
│ ✓ Task 1: Add authentication [COMPLETED] 45s │
│ ⟳ Task 2: Write tests [IN_PROGRESS] 12s │
│ └─ [View Live Output ▼] │
│ ⏸ Task 3: Update docs [WAITING] (depends on 2) │
│ ✗ Task 4: Deploy API [FAILED] 8s │
│ └─ [View Error ▼] │
│ ● Task 5: Lint code [READY] │
│ │
│ [Pause All] [Cancel Batch] │
└─────────────────────────────────────────────────────┘
Key UX Details:
- Parallel execution indicator: Highlight tasks running simultaneously
- Click to expand: Each task row expands to show live event stream
- Retry failed tasks: Button to retry only failed tasks in batch
DON'T BUILD:
- ❌ Task templates UI (CLI has
cf templates) - ❌ Custom agent configuration (tech stack is auto-detected)
- ❌ Multi-workspace switcher (one workspace per session)
- ❌ Task editing UI (tasks are generated from PRD)
- ❌ Historical analytics (no dashboards or charts)
- ❌ User management (single-user tool)
- ❌ Notification center (SSE events in context are enough)
DON'T BUILD:
- ❌ Optimistic updates (wait for API confirmation)
- ❌ Offline mode (assume network connectivity)
- ❌ Undo/redo (git handles rollback)
- ❌ Draft states (PRD discovery is the only "draft")
DON'T BUILD:
- ❌ Live collaboration (no multiplayer)
- ❌ Cursor positions (no "typing" indicators)
- ❌ Live file preview (diffs on completion are enough)
- ❌ WebSocket fallbacks (SSE is sufficient)
DON'T BUILD:
- ❌ Custom design system (use Shadcn/UI as-is)
- ❌ Theming engine (stick to Tailwind CSS)
- ❌ Plugin architecture (no extension points)
- ❌ Internationalization (English-only for v1)
DON'T BUILD:
- ❌ Drag-and-drop task reordering (tasks ordered by dependencies)
- ❌ Resizable panels (fixed layouts are fine)
- ❌ Keyboard shortcuts (mouse-first is acceptable)
- ❌ Multi-window support (single-tab experience)
DON'T BUILD:
- ❌ Terminal emulator (translate to visual components)
- ❌ Command palette (normal navigation is fine)
- ❌ Log viewer (design for readability, not raw text)
| View | Purpose | Key Component | Real-time? |
|---|---|---|---|
| Workspace | Overview & initialization | WorkspaceStatsCards | Static |
| PRD | Document creation & discovery | DiscoveryPanel | SSE (discovery chat) |
| Tasks | Kanban board & batch controls | TaskCard grid | Poll on nav |
| Execution | Monitor AI agent work | EventStream | SSE (execution events) |
| Blockers | Answer agent questions | BlockerCard with inline form | Poll on nav |
| Review | Inspect & commit changes | DiffViewer + CommitPanel | Static |
| PROOF9 | Run gates, view evidence, run history | GateEvidencePanel + RunHistoryPanel | Poll after run |
- Navigation: Left sidebar (persistent), URL-driven, auto-navigate on execution start
- Real-time: SSE for execution and discovery only, simple polling elsewhere
- Minimal: Every screen serves the golden path, every component is essential
- Elegant: Clean, crisp UI focused on the task at hand