UI Content Requirements — Personal Workstation

Requirements-only UI interview. Establishes data, actions, states, and constraints per screen without committing to layout or component decisions.
Source: specs/user-flow-personal-workstation.md (approved 2026-06-10) • Interview conducted 2026-06-10

Evidence Coverage

Source	Status	Key Inputs
`specs/user-flow-personal-workstation.md`	Primary	10 screens, state matrices, entry points, failure paths, wireframe notes
`research/positioning.md`	Read	Competitive framing, core differentiators, zero-inbound networking
`research/journey-map.md`	Read	Aha moment, onboarding flow, mobile approval routing
`research/icp.md`	Read	Solo developer persona, 5–12 agents, multi-repo workflow
`research/concept-brief-gblock-party-personal.md`	Read	BYO-client model, PWA, managed infrastructure
Existing codebase	N/A	No code exists — greenfield project in research/planning phase

Gate 1: Is the evidence base sufficient for UI content requirements?

Yes — evidence is sufficient, proceed Evidence has gaps but proceed with noted caveats Insufficient — need more upstream research before UI requirements Other

Assumptions Manifest

Confirmed During Interview

#	Assumption	Source
1	Solo developer managing 5–12 AI coding agents — no team/collaboration features	[from spec]
2	Three access modes: Dashboard (A), Terminal (B), IDE (C)	[from spec]
3	PWA — installable on mobile and desktop, service worker for push	[from spec]
4	BYO-client — users connect providers via OAuth (where supported) or API key, using their own subscriptions and billing	[from spec]
5	GitHub App installation is sole auth mechanism — identity via GitHub OAuth, repo access via GitHub App installation grants (user selects all or specific repos)	[from spec]
6	10 screens: S1–S10 as defined in user flow map	[from spec]
7	S3 Agent Board is home after auth — all screens reachable from it	[inferred]
8	S4 Start Agent is a modal overlay (not a separate route) — triggered from S3, tab bar "+" button on any screen, or mobile bottom nav	[interview]
9	S7 Approval appears in three contexts: standalone mobile view, inline in S5, and indicator on S3	[interview]
10	Mobile header is minimal; QR on mobile is for sharing to tablet/other phone	[interview]
11	Browser-like tab navigation on all web views (desktop + tablet): pinned tabs (Agent Board, Approvals), dynamic tabs (agent sessions, diffs), and a persistent + button to open S4 Start Agent modal from any screen — can live as sidebar or top bar	[interview]
12	Custom hotkeys for session switching (Ctrl+1..N), session switching only	[interview]
13	Open tabs persist across devices (server-tracked, not client-local)	[interview]
14	WebSocket for real-time agent status, stdout streaming, approval notifications	[from spec]
15	Server-canonical state — all devices see the same state	[from spec]
16	Mobile uses bottom nav (Agent Board, Approvals, Settings, + Start Agent) and hamburger for open tabs	[interview]
17	Provider auth is hybrid OAuth/API-key per provider: OpenAI supports "Sign in with ChatGPT" subscription passthrough (prefer OAuth, API key fallback); Anthropic bans subscription OAuth in third-party tools (always API key). Auth method is provider-determined, not user-chosen.	[interview]

Gate 2: Are the assumptions and confidence levels correct?

All correct — no changes needed Minor adjustments needed (note below) Major issues — rethink before proceeding Other

Global Shell

Desktop Header Revised

Element	Data / Entity	Cardinality	Notes
App name / logo	Static brand mark	One	Links to S3 Agent Board
Notification bell	Unread notification count badge	One (aggregate)	Opens notification inbox. Currently surfaces approval notifications; extensible to org/team notifications in the future. Approvals pinned tab remains the primary approval queue — bell is for cross-cutting notifications.
Running agent count	Count of agents in "running" state	One (aggregate)	At-a-glance status indicator
Settings gear	Navigation trigger	One	Opens S10 Settings
Share button	Opens share modal	One	Modal includes: share by link (short-lived pre-authenticated deep link), email teammate (future — teams/org support), and QR code for mobile/tablet handoff
User avatar / account menu	GitHub profile image, session controls	One	Logout, session info

Tab Bar (All Web Views — Desktop + Tablet) Revised

Element	Behavior	Persistence
Pinned: Agent Board	Always present, not closeable	Server-persisted
Pinned: Approvals	Always present, not closeable. Badge shows pending approval count.	Server-persisted
Dynamic: Agent session tabs	Opens when user clicks into an agent (S5/S6). Closeable.	Server-persisted across devices
Dynamic: Diff review tabs	Opens when user enters S9 for a specific agent. Closeable.	Server-persisted across devices
+ New Agent	Always present, pinned to the right end of the tab row (VS Code / Windows Terminal convention). Opens S4 Start Agent modal from any screen — user does not need to navigate to S3 first.	N/A (action trigger)

Mobile Shell Revised

Element	Location	Behavior
Notification bell	Top header (always visible)	Minimal — unread count badge on bell icon
Hamburger menu	Top header	Opens drawer listing all open dynamic tabs (agent sessions, diffs). Hidden on the Agent Board screen — the board itself already displays all sessions, and Approvals is one bottom-nav tap away, so the tab drawer adds no value there. Appears only when the user is inside a detail view (S5/S6/S9) and needs to switch between open tabs.
Agent Board	Bottom nav	Pinned — always visible
Approvals	Bottom nav	Pinned — with badge
Settings	Bottom nav	Pinned
+ Start Agent	Bottom nav	Opens S4 Start Agent modal

Custom Hotkeys

Scope: Agent session switching only (Ctrl+1 through Ctrl+N)
Configuration: Managed in S10 Settings
Persistence: Server-persisted, available on any device with keyboard

States

State	Trigger	Behavior
Unauthenticated	No valid session	No shell shown — only S1 Auth
Connection lost	WebSocket heartbeat timeout	Banner in header: "Reconnecting..." with auto-retry
Zero agents	No agents configured	Tab bar shows pinned tabs only, no dynamic tabs

S1 — GitHub Authentication Revised

Data Fields Revised

Field	Type	Source
GitHub identity	GitHub App installation + OAuth web flow for user auth	GitHub API
Permissions granted	Fine-grained: repository contents (read/write), user email (read)	GitHub App installation prompt
Repository scope	User-selected: "All repositories" or "Only select repositories"	GitHub App installation prompt
Session token	JWT or secure cookie	Generated server-side post-OAuth

User Actions

Login with GitHub: Primary action — redirects to GitHub App OAuth web flow for user auth + installation for repo access
QR code auto-auth: If arrived via QR scan, one-time token bypasses manual OAuth

States

State	Trigger	Display
Initial	First visit or session expired	"Login with GitHub" button
Redirecting	User clicked login	Brief loading indicator as browser redirects to GitHub
Callback processing	GitHub redirects back	Skeleton loading — straight-through routing to S3 or S2
Auth error	OAuth failed (denied scopes, network error)	Error message with retry option
QR token expired	One-time token from QR has expired	Falls back to standard OAuth login

Constraints Revised

Uses GitHub App (not classic OAuth App) — user selects which repositories to grant during installation
No intermediate "connecting to workspace" screen — straight through to S3/S2
Skeleton loading renders if data fetches are in flight
QR auto-auth must validate one-time token server-side before issuing session

S2 — Setup Wizard Revised

Data Fields Revised

Field	Type	Cardinality	Required?
Discovered repos	List of GitHub repos populated from GitHub App installation grants (user controls scope: all repos or selected repos during installation)	Many	Auto — populated from user's GitHub App grants
Provider credentials	Per-provider auth — OAuth ("Sign in with ChatGPT") where supported, API key entry where not	Many (one per provider)	At least one
Provider auth method indicator	Per-provider badge: "OAuth" or "API Key" — shown next to each provider so user knows what to expect	Many	System-generated
Notification preferences	Push notification opt-in, email fallback toggle	Few	Optional (defaults available)
Infrastructure status	Health check results per tool and connectivity — rendered inline as status indicators within the Setup Summary, not a standalone view	Many	System-generated

User Actions Revised

Connect provider: OAuth flow for providers that support it (e.g., "Sign in with ChatGPT" button), or API key entry for providers that require it (e.g., Anthropic). Validated on completion.
Configure notifications: Choose push notifications, email notifications, or off
Review setup summary: Confirm repos, connected providers, and notification settings. Health check runs automatically in background.
Finish setup: Click "Finish Setup" from the summary to proceed to S3.

Flow Structure Revised

Multi-step wizard with progress indicator:

Step 1 — Provider Auth: Connect model providers — OAuth where supported (e.g., "Sign in with ChatGPT"), API key entry where required (e.g., Anthropic). Auth method badge shown per provider. Validation on completion. At least one provider required.
Step 2 — Notifications: Three options: push notifications, email notifications, or off.
Step 3 — Setup Summary: Read-only confirmation of everything configured. Three groups: (1) Repos — list of GitHub repos from App installation grants, (2) Connected Providers — each provider with auth method badge (OAuth / API Key) and connectivity status, (3) Notification Setting — the preference chosen in Step 2. Health check runs automatically in the background; results appear inline as status indicators next to each provider and repo entry. "Finish Setup" CTA at the bottom.

States Revised

State	Trigger	Display
Step active	User on current wizard step	Current step form + progress indicator showing position
Validating key	User entered an API key	Inline spinner + "Validating..." on the field
Key valid	API key validated successfully	Green check on field
Key invalid	API key validation failed	Red error message inline
OAuth redirecting	User clicked provider OAuth button (e.g., "Sign in with ChatGPT")	Browser redirecting to provider — spinner or "Redirecting to [provider]..." indicator
OAuth connected	Provider OAuth succeeded — callback received	Green check with provider badge showing "OAuth" and subscription tier (e.g., "ChatGPT Plus")
Health check running	Step 3 started	Summary loaded; inline spinners next to each provider/repo while connectivity is verified
Health check failed	One or more tools unreachable	Failed items show inline warning icon + retry link within the summary. "Finish Setup" remains enabled.
Complete	All steps done	All items show final status. "Finish Setup" CTA enabled at bottom of summary.

Constraints Revised

Minimum viable setup: GitHub OAuth (already done) + one provider connected (OAuth or API key)
Repos populated from GitHub App installation grants — user controls scope during GitHub App setup (all repos vs. selected repos)
Health check is automated but non-blocking — failures display per-tool warnings but do not block setup completion. User can proceed to Agent Board; failed tools are flagged in S10 Settings for later resolution.
Running Claude Code CLI in gblock-party's managed infrastructure with the user's own Anthropic API key is within Anthropic ToS. The subscription OAuth ban targets credential passthrough, not BYOK API-key usage of the official CLI.
Provider auth method is provider-determined, not user-chosen. gblock-party shows the correct auth UX per provider automatically.
Anthropic explicitly bans subscription OAuth in third-party tools (Feb 2026 terms, enforced April 4 2026) — always API key with usage-based billing.
OpenAI supports "Sign in with ChatGPT" subscription passthrough (since April 2026) — prefer OAuth, offer API key as fallback.

S3 — Agent Board

Data Fields — Agent Card (Canonical)

Field	Type	Default Visible?	Customizable?
Agent name / label	String (user-assigned or auto-generated)	Yes	No (always shown)
Status badge	Enum: running, idle, waiting, error, starting, complete	Yes	No (always shown)
Tool name	String (Claude Code, Codex, Aider, etc.)	Yes	Yes
Repository	String (owner/repo)	Yes	Yes
Branch	String	No	Yes
Elapsed time	Duration since agent started	Yes	Yes
Stdout preview	Last line of parsed stdout	Yes	Yes
Token usage	Numeric (tokens consumed)	No	Yes
Token cost	Currency estimate	No	Yes
Files changed count	Numeric	No	Yes
Last activity timestamp	Relative time ("2m ago")	No	Yes

Card Customization

Trigger: Prompted after user's first session (contextual onboarding, not in wizard)
Mechanism: Fixed menu of ~10 toggle-able fields. Sensible defaults pre-selected.
Dismissible: "Use defaults" skips customization
Later access: Card configuration available in S10 Settings

User Actions

Start new agent: Opens S4 modal (also reachable from tab bar "+" button on any screen)
Click agent card: Opens S5 Agent Detail (or S6 Terminal) as a dynamic tab
Filter: Filter by status, repo, or tool via filter chips
Group: Optional grouping by repo or status
Sort: Auto-sort by priority (error > waiting > running > idle > complete)
View approvals: Navigate to Approvals pinned tab

Approval Indicator on S3

Agent cards in "waiting" state show a visual approval indicator
Cards with pending approvals sort above running agents
Pinned Approvals tab badge provides aggregate visibility

States

State	Trigger	Display
Empty	No agents configured	"Start your first agent" CTA + quick-start guide
All running	All agents actively processing	Grid of cards with live stdout preview, elapsed time
Mixed status	Agents in various states	Cards sorted by priority
Approval pending	One or more agents waiting	Waiting cards highlighted, badge visible on Approvals tab and notification bell
All complete	All agents finished	Completion summaries, "Review diffs" CTA prominent
Connection lost	WebSocket heartbeat timeout	Banner: "Reconnecting..." — last-known state shown

Relationships

Agent → Repository: Many-to-one (multiple agents can work on same repo)
Agent → Tool: One-to-one (each agent uses one tool)
Agent → Approvals: One-to-many (agent can have pending approval queue)

S4 — Start Agent Modal

Trigger Points Revised

Tab bar "+" button (right end): Available on every web screen — primary global entry point
S3 Agent Board: "Start new agent" action within the board
Mobile bottom nav: "+ Start Agent" button in bottom navigation

Data Fields — Primary

Field	Type	Required?	Source
Repository	Dropdown (auto-populated from GitHub App installation grants)	Yes	GitHub API
Tool	Dropdown (headless-viable tools available in workspace)	Yes	Workspace config
Initial prompt	Textarea (free text)	Yes	User input
Branch	Text field or dropdown	No (defaults to main/master)	GitHub API + user input

Data Fields — Advanced (Collapsible Section)

Field	Type	Required?	Notes
Agent label	Text field	No	Custom name for the agent session (auto-generated if empty)
Prompt template	Dropdown of saved templates	No	Pre-fills the initial prompt textarea
Resource tier	Dropdown (light / standard / heavy)	No	Controls CPU/memory allocation
Working directory	Text field (path within repo)	No	Defaults to repo root
Environment variables	Key-value pairs	No	Injected into agent process environment

User Actions

Start Agent: Primary action — validates required fields, launches agent process
Cancel: Closes modal, returns to S3
Expand advanced: Toggle collapsible advanced options
Select template: Pre-fills prompt from saved template

States

State	Trigger	Display
Ready	Modal opened, data loaded	All fields enabled, Start button enabled when required fields filled
Loading repos	Modal opened, fetching repo list	Skeleton loaders in repo picker
Launching	User clicked Start	Spinner on button, fields disabled
Error	Launch failed	Error message with retry, fields re-enabled
Tool unavailable	Selected tool not in workspace	Warning with link to S10 to install tool

Constraints

All three primary fields (repo, tool, prompt) required before Start enables
Advanced section collapsed by default — one-click launch path stays simple
Repo picker auto-populated from GitHub App installation grants — no manual URL entry

S5 — Agent Detail (Structured)

Data Fields

Field	Type	Cardinality	Update Frequency
Agent name / label	String	One	Static
Status	Enum: running, idle, waiting, error, starting, complete	One	Real-time
Tool + repo + branch	Strings	One each	Static per session
Parsed stdout	Structured text stream (Multica-style parsing)	Streaming	Real-time
Task progress	Step indicators (if tool supports structured progress)	Many	Real-time
File change list	List of filenames with change type (added/modified/deleted)	Many	Real-time as agent modifies files
Token usage	Numeric (running total)	One	Periodic
Elapsed time	Duration	One	Continuous
Inline approval card (S7)	Approval request with diff preview	Zero or one	Event-driven

User Actions

View file diff: Click filename in change list → opens S9 Diff Review in new dynamic tab
Approve/reject (inline): When S7 approval card appears inline, take action without leaving S5
Inject prompt: Send additional instructions to the running agent via textarea
Stop agent: Halt agent process (with confirmation)
Restart agent: Restart with same or modified prompt
Switch to terminal: Open S6 terminal view for this agent

States

State	Trigger	Display
Streaming	Agent actively producing output	Live parsed output, progress indicators, file list updating
Waiting for input	Agent paused for approval	Inline S7 approval card, prompt injection visible
Idle	Agent finished current task	Completion summary, "Assign next task" CTA
Error	Agent crashed	Error details, stack trace, retry/restart buttons
Reconnecting	WebSocket dropped	"Reconnecting..." overlay, buffered output replays on reconnect

Relationships

S5 → S6: Same agent, different view mode (structured vs terminal). Togglable.
S5 → S7: Approval cards appear inline within S5 when agent requests approval
S5 → S9: File list items link to diff review for that file

S6 — Agent Terminal

Data Fields

Field	Type	Notes
Terminal output	Raw terminal stream (xterm.js rendering)	Full ANSI/escape code support via WebSocket to tmux
Agent name / status	String + enum	Shown in tab title or minimal header
Keyboard input	Keystroke stream to tmux session	Sub-100ms echo target

User Actions

Type commands: Full interactive terminal — keyboard input sent to tmux session
Switch to structured: Toggle back to S5 structured view
Resize terminal: Terminal resizes with viewport (responsive)
Copy text: Standard terminal text selection and copy

Desktop Layout

Default: Split view — terminal on one side, S5 structured output on the other
Option: User can maximize terminal to full viewport

Mobile Layout

Always full-screen terminal — split view not practical on mobile
Toggle to S5 structured view via button/swipe

States

State	Trigger	Display
Connected	WebSocket attached to tmux session	Live terminal, full interactivity
Reconnecting	WebSocket dropped	"Reconnecting..." overlay, auto-retry
Session ended	Agent process terminated	Terminal frozen with last output, "Agent stopped" indicator

Constraints

Target: sub-100ms keystroke echo (latency budget — see open question #2)
Terminal buffer replays on reconnect — no output lost
Desktop split view: terminal + structured output side by side

S7 — Approval Request

Three Rendering Contexts

Context	Where	When	Optimized For
Standalone mobile	Dedicated view via push notification deep link	User taps notification on phone	Quick one-tap approve/reject, large touch targets
Inline in S5	Embedded card within Agent Detail	User is already viewing the agent	Context — agent output visible alongside approval
Indicator on S3	Agent card badge/highlight on Agent Board	Approval pending for an agent	Visibility — user sees pending approvals at a glance

Data Fields

Field	Type	Cardinality
Agent name	String	One
Wait duration	Duration since approval requested	One
Description	Agent's explanation of what it wants to do	One
Diff preview	3–5 lines of diff context, expandable to full	One (expandable)
Risk assessment	Agent-generated risk level (if available)	Zero or one
Proposed action	What the agent will do if approved	One

User Actions

Action	Type	Notes
Approve	Primary positive action	Agent resumes immediately. Sub-second delivery via internal API.
Reject	Primary negative action	Reveals rejection reason textarea. Agent receives feedback.
Modify / redirect	Compound action	Preset responses ("retry different approach", "skip this file", "proceed cautiously") + free-text textarea for custom instructions
Defer	Neutral action	Leave for later — agent remains paused, approval stays in queue
Expand diff	Navigation	Expand from 3–5 line preview to full diff view

Approval Queue

Multiple approvals displayed as a queue (FIFO order, priority-sortable)
Batch approve option when multiple agents request similar actions
Queue accessible from Approvals pinned tab

States

State	Trigger	Display
Pending	Agent requested, user hasn't acted	Full approval card with actions
Reviewing	User expanded full diff	Full diff viewer with agent context
Approved	User approved	Brief confirmation, auto-return to previous context
Rejected	User rejected with feedback	Rejection sent, agent adjusts
Expired	Configurable timeout elapsed	Grayed card, still actionable or auto-rejected per settings

Constraints

Mobile: large touch targets for approve/reject (minimum 48px)
Push notification deep link must open directly to the relevant approval
Preset responses are not hard-coded — list should be extensible via S10 Settings

Gate 3: Are the screen requirements for S1 through S7 accurate and complete?

Complete — all data, actions, and states captured correctly Minor gaps — mostly right, note adjustments below Major gaps — significant requirements missing Other

S8 — Async Recap

Data Fields

Field	Type	Cardinality
Time window	Duration since last interaction	One
Event timeline	Chronological list of events	Many
Completed tasks	List of agents that finished work	Many
Pending approvals	Count + summary of waiting approvals	Many
Errors	Agents that encountered errors during absence	Many
PRs created	List of pull requests auto-created by agents	Many
Urgent items	Errors + expired approvals — highlighted subset	Many

Event Types

Task completed (agent finished its work)
Approval pending (agent waiting for user action)
Error occurred (agent crash or failure)
PR created (agent auto-created a pull request)
Approval expired (timeout elapsed without action)
Agent auto-restarted (transient error recovery)

User Actions

Navigate to agent: Click event to open relevant agent in S5
Navigate to approval: Click pending approval to open S7
Navigate to diff: Click completed task to open S9 for review
Dismiss recap: "Got it" button redirects to S3

States

State	Trigger	Display
Activity summary	User returns after absence (> threshold)	Timeline of events with urgent items at top
Nothing new	Agents were idle during absence	"All quiet" message, direct navigation to S3
Urgent items	Errors or expired approvals	Urgent items highlighted with distinct styling at top
Dismissed	User clicked "Got it"	Redirect to S3; recap accessible from history

Constraints

Full page view — user sees recap before Agent Board after a gap
Absence threshold is configurable (default TBD — e.g., 15 minutes)
Recap is not blocking — user can skip/dismiss immediately
Recap history accessible later (not a one-time view)

S9 — Diff Review

Data Fields

Field	Type	Cardinality
File tree	Hierarchical list of changed files	Many (nested)
Diff content	Unified or side-by-side diff per file	One per file
Commit history	List of commits from agent session	Many
Agent context	Agent name, tool, repo, branch	One
Inline comments	User-authored comments on specific lines/hunks	Many
Change statistics	Lines added/removed, files changed	One (aggregate)

User Actions

Toggle diff mode: Switch between unified and side-by-side (split) view
Navigate files: Click file in tree to jump to that file's diff
Add inline comment: Click line gutter to add comment on a specific line or hunk
Approve and merge: Merge the changes (creates or merges PR via GitHub API)
Request changes: Send feedback to agent with inline comments
Create PR: Push changes and create a GitHub pull request
Discard: Reject changes entirely (with confirmation)

States

State	Trigger	Display
Reviewing	User opened diff for an agent	File tree + diff viewer, action buttons
Commenting	User adding inline comments	Comment textarea appears at selected line
Submitting	User clicked approve/create PR	Spinner, "Creating PR..." message
Submitted	PR created successfully	Success message with PR link
Conflict	Merge conflict detected	Conflict markers shown, option to resolve in S6 terminal

Constraints

Full GitHub PR review experience — unified/split toggle, inline comments, file-by-file nav
Mobile: stacked layout (file tree above, diff below) — no side-by-side split
Inline comments are sent to the agent as structured feedback if "request changes" is used
PR creation uses GitHub API via the GitHub App installation token

S10 — Settings Revised

Data Fields — Sections

Section	Data	Cardinality
Tools & Provider Auth	Per-tool config: OAuth connection or API key, enabled/disabled, health status indicator	Many (one per tool)
Notifications	Push notification toggle, email fallback, notification sound, approval timeout	Few
GitHub App	Connected account, installation grants (all vs. selected repos), re-authorize link	One
Infrastructure Status	Backend connectivity, tunnel status, resource usage (CPU/memory/disk)	One (live)
Card Customization	Toggle-able field list for S3 agent cards	~10 fields
Hotkeys	Key binding map for session switching (Ctrl+1..N)	Many
Tab Preferences	Tab bar position (top/sidebar), behavior settings	Few
Approval Presets	Editable list of preset approval responses for S7	Many
Danger Zone	Reset workspace, revoke access, delete all data	Few

User Actions

Add/update provider auth: Connect via OAuth or enter/rotate API key per provider (validated on save)
Toggle tool: Enable/disable tools
Run health check: Re-verify connectivity per tool
Re-authorize GitHub: Re-run GitHub App installation to update repo grants
Configure notifications: Toggle push, set email fallback, adjust timeout
Customize card fields: Toggle which fields appear on S3 agent cards
Configure hotkeys: Map Ctrl+N shortcuts to agent sessions
Edit approval presets: Add/remove/reorder preset responses for S7
Reset workspace: Destructive action (confirmation required)
Revoke access: Disconnect GitHub, clear session (confirmation required)

States

State	Trigger	Display
Normal	Settings page opened	All sections with current values
Saving	User changed a setting	Inline save indicator on changed field
Validating	API key entered	Spinner + "Validating..." on field
Health check running	User triggered health check	Per-tool progress indicators
Danger confirmation	User clicked destructive action	Confirmation dialog with consequences described

Constraints

Single settings surface — all configuration in one place
Auto-save on field change (no "save" button for most settings)
Danger zone visually separated and requiring explicit confirmation
Health check per-tool, not all-or-nothing

Gate 4: Are the screen requirements for S8 through S10 accurate and complete?

Complete — all data, actions, and states captured correctly Minor gaps — mostly right, note adjustments below Major gaps — significant requirements missing Other

Prototype-First Boundary

First Clickable Journey

S1 Auth → S3 Agent Board (mock data, 3–5 agents in various states) → S4 Start Agent (form submits but uses fixture) → S5 Agent Detail (fake streaming stdout) → S7 Approval (approve action with mock response)

Fixture / Fake Data

Mock agent cards: 3–5 agents with mixed statuses (running, idle, waiting, error, complete)
Fake stdout streams: pre-recorded output that replays to simulate real-time streaming
Sample diffs: realistic multi-file diffs for S9 review experience
Mock approval requests: 1–2 pending approvals with diff previews
Fake recap data: timeline of events for S8 demonstration

Infrastructure to Mock Visually (Not Implement)

WebSocket connections — simulate with polling or replayed data
tmux sessions — terminal widget with pre-recorded output
Process supervisor — "Start Agent" adds a fixture agent card
GitHub OAuth — mock auth flow or hardcoded session
Push notifications — mock notification list, no real push subscription
GitHub API (PR creation, repo list) — fixture repo list, mock PR creation

Deferred from Prototype

Code-server / Mode C (IDE): Most complex, uncertain ROI — defer entirely
Real WebSocket infrastructure: Use simulated real-time for prototype
Backend process supervisor: No real agent process management
Tailscale/WireGuard tunnel: No real networking
Multi-device sync: Demonstrate concept with fixture, not real server-canonical state
BYO-client connectivity: Load-bearing assumption still unvalidated

Questions Prototype Must Answer

Does the Agent Board → Agent Detail → Approval flow feel fast and natural?
Is the tab navigation intuitive for managing multiple agent sessions?
Does the mobile bottom nav + hamburger pattern work for quick check-ins?
Is the card customization prompt well-timed (after first session)?
Does split view (terminal + structured) on desktop feel productive or cramped?

Gate 5: Is the prototype boundary well-scoped?

Good — prototype scope is right for validating the core experience Too broad — reduce prototype scope Too narrow — need more in the prototype to validate Other

Proposed File Changes

Action	Path	Description
Create	`specs/ui-requirements-personal-workstation.md`	Content requirements spec — all screens, data, actions, states, constraints
Create	`ui-requirements-personal-workstation-interview.md`	Interview log — questions asked, options presented, user decisions

Gate 6: Are the proposed file changes approved?

Approved — write both files as specified Write files but at different paths (specify below) Write spec only, skip interview log Other

Coverage Checkpoint

Category	Coverage	Status
Global Shell (desktop + mobile)	Header, tab bar, bottom nav, hotkeys, connection states	Complete
S1 Auth	GitHub App installation + OAuth flow, QR auto-auth, error states	Complete
S2 Setup Wizard	Multi-step flow, API keys, notifications, health check	Complete
S3 Agent Board	Card fields, customization, sort/filter/group, approval indicators, 6 states	Complete
S4 Start Agent	Primary + advanced fields, 5 states	Complete
S5 Agent Detail	Parsed stdout, file list, inline approval, prompt injection, 5 states	Complete
S6 Terminal	xterm.js, split/full-screen, desktop/mobile, 3 states	Complete
S7 Approval	3 contexts, 4 actions with presets, queue, 5 states	Complete
S8 Async Recap	Timeline, event types, urgent items, 4 states	Complete
S9 Diff Review	Unified/split, file tree, inline comments, PR creation, 5 states	Complete
S10 Settings	9 sections, all config consolidated, auto-save, danger zone	Complete
Prototype boundary	First journey, fixture data, mocked infra, deferred items, validation questions	Complete
Responsive behavior	Desktop vs mobile noted per screen; mobile shell defined	Complete
Accessibility	Not covered (requirements-only — deferred to full UI interview or UX variations)	Deferred
Data relationships	Agent→Repo, Agent→Tool, Agent→Approvals documented	Complete

Open Risks

Accessibility: Deferred to full /ui-interview or /ux-variations — color-blind safe, keyboard nav, screen reader labels not yet specified
Approval preset extensibility: User confirmed presets + free text; exact default preset list not defined
Recap absence threshold: Default duration (e.g., 15 min) not confirmed
Tab bar position: Top vs sidebar left as a user preference — not locked
Card customization field list: Exact ~10 fields listed but could expand

Gate 7: Is the coverage checkpoint satisfactory?

Satisfactory — proceed to write deliverables after all gates approved Missing items — need to address gaps before writing Other

Compile Review

Use Compile Feedback to send concerns or clarification requests before answering every gate, or Compile Answers for final approval once all required gate questions are answered. The compiled YAML always includes any optional section feedback you set.