UX Variations — monitoring-start

1. Name & Thesis

Operator Console. The agent fleet is a NOC (Network Operations Center — the always-on monitoring room where operators watch a wall of live system status and act the moment something turns red). One dense, sortable, filterable data table — one row per agent, 5–12 rows — with a persistent split-pane: the table holds the left column, the selected agent’s tool-adaptive detail holds the right. The fleet never leaves view. You triage like an SRE reading a monitoring dashboard: scan the status column, sort errors to the top, act inline (approve / unblock / stop) without leaving the row, and keep one agent open in the detail pane while the other eleven keep streaming beside it.

One-line thesis: Maximum-density, keyboard-driven fleet command — every agent on one screen, every action one keystroke away, drill-in without ever losing the fleet.

The design bet: a solo conductor running 12 agents does not want twelve cards to scroll through; they want a spreadsheet of their fleet and a terminal stapled to its side. Density is the feature, not a regression to apologize for.

2. Parent User Flow & Branch Relationship

This variation is one of five sibling treatments of the monitoring-start branch (Happy Path steps 3–6 + Path C “Parallel Sprint”). All five serve the same two-layer surface and contrast only in how the orchestration layer (S3/S4) connects to the deep-work layer (folded S5/S6).

Relationship to siblings: V1 sits at the explicit desktop-dense extreme of the device-posture axis (the brief’s deliberate counterweight to v5’s mobile-first). It shares v4’s keyboard-native instinct but diverges on glanceability: v4 hides the fleet behind a palette and shows a quiet list; V1 puts the entire fleet on screen at all times as structured tabular data. It is the antithesis of v2’s roomy cards. Mobile is V1’s deliberate degrade case, not its design center — that territory belongs to v5.

This spec carries the brief’s confirmed reframe (two-layer surface; folded tool-adaptive detail; all-web PWA) and does NOT silently edit the approved flow-map. Where it departs from flow-map structure, that is recorded in §11.

3. Target User Fit

Best fit: the keyboard-driven power user at peak load — the conductor running 8–12 concurrent agents across 2–3 repos from a wide desktop monitor, who lives in tmux/htop/k9s/Grafana and reads tables faster than cards. They want information per pixel, not whitespace; they sort and filter reflexively; they expect j/k to move and Enter to open.

Poor fit: a first-time user meeting agents for the first time (the table reads as intimidating cockpit chrome before there is anything to monitor); a phone-primary “quick-check” user (the table must collapse to survive small screens); a 1–3 agent light user (the density buys nothing — a card grid would serve them better, which is why v2 exists).

Fit signal: if the evaluator, during UAT, instinctively sorts the status column and uses keyboard nav to triage a 10-agent fleet faster than they did in v2/v5, this variation is earning its density.

4. Onboarding / Activation Model (first meeting + empty state)

V1 owns only the monitoring-start surface; first-run provisioning (S2 Setup Wizard, Path A) is upstream and out of scope. The activation question here is: how does a first-time user meet a NOC table with zero rows?

Empty state (zero agents): the table chrome is suppressed, not shown empty. A spreadsheet of nothing is hostile. Instead the split-pane collapses to a single centered column:

• Headline: “Your console is empty. Launch your first agent.”
• One large primary action: + New Agent (opens the inline launch row, pre-focused).
• A secondary hint line: “Press ⌘K anytime to launch, jump, or filter.” — teaching the keyboard model on day one.
• A 3-step quick-start strip (Pick repo → Pick tool → Write prompt), each step a faint preview of the inline launch row fields.
• The right detail pane shows a static legend: what each status badge means (idle / running / waiting / error / starting / stopped), so the user learns the vocabulary before the first row exists.

First-agent transition (activation moment): when the first agent launches, the empty column animates into the two-region split-pane. The first row appears with starting status and the detail pane auto-selects it (the only sensible selection), immediately showing live stdout. This is the “the console is now live” beat — the table header (sort/filter controls) fades in only once ≥1 row exists, so the user is never shown empty machinery.

Density ramp: columns are progressive. At 1–3 agents the table shows the full column set comfortably. The user is not asked to configure columns on day one; column customization is a power affordance discovered later (§14), never a setup gate.

5. Typical Workflow Sequence (orchestrate → drill-in loop)

The core loop. Numbered, keyboard-first, with mouse equivalents in parentheses.

1. Open PWA → S3 console. Returning user lands on the populated table, default sort error > waiting > running > idle. The previously-selected agent is restored into the right pane (server-canonical; survives device switch).
2. Scan the status column. Errors and approval-waits are sorted to the top and color-coded. A header chip shows counts: 2 waiting · 1 error · 7 running. Triage is a single visual sweep of the leftmost columns.
3. Triage inline without drilling in. For a clear approval, press a on the focused row (or click the inline Approve affordance) — the row’s diff micro-preview expands one tier in place; confirm. For a blocked agent, u to unblock. For a runaway, x to stop (guarded, §15). The fleet stays put; no navigation.
4. Drill in when a row needs attention. j/k (or arrow keys / click) to move the row cursor; Enter (or click the row) selects it into the right detail pane. The other 11 rows stay visible and keep streaming. This is the signature move: drill-in is selection, not navigation.
5. Work the agent in the folded detail pane. The pane renders tool-adaptively (terminal-primary for CLI tools, structured for API-native — §13). Type into the terminal, read the structured step stream, inject a prompt, approve inline. The fleet table on the left keeps updating in your peripheral vision.
6. Fan out a parallel sprint (Path C). To launch agent #2/#3 mid-flow: n (or click the inline + New Agent row pinned to the top of the table) — the top row becomes editable inputs (repo · tool · prompt). Fill and ⌘Enter to launch. New starting row drops into the table. Alternatively ⌘K → “New agent…” for a full quick-launch palette without leaving the keyboard.
7. Round-robin approvals. As more agents hit decision points they sort to the top and the header count increments. Walk them: focus top waiting row → a → confirm → focus next. Or ⌘K → “Approve all clear” for the batch path (§15).
8. Return to monitoring. Esc deselects the detail pane (collapses it wider on demand, §13) and returns focus to the table. Loop back to step 2.

The loop never leaves the single console route. Steps 2–3 are pure orchestration; steps 4–5 are deep-work; the split-pane is what fuses them.

6. Progression Model — and how it differs from the 4 siblings

How the user advances through the flow in V1: progression is lateral, not navigational. The user does not move between screens to advance; they move the selection cursor down the table and the detail pane updates underneath them. Advancement = re-sorting (state changes float rows up), selecting (binds a row to the pane), and acting inline (mutates state, which re-sorts). The flow’s S3→S5/S6 transition is collapsed into a pane-bind on one persistent route. There is no back-stack to manage because you never left the board.

Explicit contrast with each sibling:

• vs v2 Card Mosaic (route-switch): v2 advances by navigating away — click a card → full-page detail route → browser back to return. Each drill-in drops board context (you can’t watch the fleet while reading one agent). V1 keeps the fleet permanently co-visible; progression costs zero context. The price V1 pays is per-row richness — v2’s cards show more stdout per agent than V1’s one-line cell.
• vs v3 Kanban Pipeline (drawer + spatial status): v3 advances by watching cards physically move between status columns (Queued→Running→Waiting→Error→Done); progression is spatial and animated, drill-in is a drawer over the board. V1 represents the identical status transitions as sort-order changes within one table (a row floats up when it errors) — quieter, denser, no card-in-flight motion. V3’s bottlenecks are visible as tall columns; V1’s are visible as clusters at the top of the sort. V1 deliberately avoids v3’s motion-instability by keeping every agent in one stable list and only reordering, never relocating between regions.
• vs v4 Command-First (palette + focus mode): v4 hides the fleet — quiet minimal list, the verb is the ⌘K palette, detail is a focus mode with the board as a back-stack. V1 and v4 share the keyboard-native soul and both offer ⌘K, but V1 never hides the fleet — full tabular glanceability is always on screen, and ⌘K is an accelerator over an already-visible board, not the primary way to perceive state. v4 trades glanceability for calm; V1 refuses that trade.
• vs v5 Glanceable Stream (mobile-first feed): v5 advances by scrolling a prioritized vertical feed designed phone-up, launches from saved recipes, detail is a full-screen sheet. V1 is its polar opposite on the device-posture axis: desktop-dense, multi-column, designed for a wide monitor; its mobile form is an explicit degrade (§17), whereas mobile is v5’s design center. v5 optimizes for the “closed laptop, checked from phone” moment; V1 optimizes for the “ten agents, one big monitor, mid-sprint” moment.

Net: V1’s progression model is “sort + select + act-in-place on one persistent dense surface.” No other sibling keeps both the full fleet and a working agent on screen simultaneously — that simultaneity is V1’s defining progression property.

7. Sharing & Collaboration Model

N/A — single-user personal workstation. This is a solo dogfood environment; there is exactly one user (the Agent Conductor) and no second human to share with, hand off to, or collaborate alongside. There are no shared boards, comments, mentions, presence indicators, or co-editing. The only “handoff” is the same user across their own devices (cross-device continuity), which is server-canonical state, not collaboration — covered under §9 return-use. No sharing affordances are designed and none should be invented.

8. Permissions Model

N/A — single-user personal workstation. There are no roles, no per-row access control, no viewer/editor tiers, no team admin. The single user has full control of every agent in the table. The only authorization in the system is GitHub OAuth, which scopes what the agents may do to the user’s repos (pull/push/PR) — an upstream identity/repo-access concern owned by S1, not a board-level permissions model. The console exposes no permission UI and none should be invented. (The OAuth-expiry failure path — agents losing repo access mid-run — is a recovery concern, handled in §10, not a permissions model.)

9. Return-Use & Notification Model

Resume: on return, the console restores server-canonical state: same rows, same statuses, same sort, and the last-selected agent re-bound into the detail pane (its stdout buffer replayed on WebSocket attach). No reconnection ceremony — this is the flow-map’s core promise. If the user returns after a gap exceeding the recap threshold (flow-map D7), a dismissible recap strip docks above the table header — not a full-screen S8 takeover, because in the Operator Console the fleet itself is the recap. The strip summarizes “while you were away: 3 completed · 2 PRs · 1 error” with each item as a chip that, when clicked, selects the relevant row into the detail pane. Esc or “Got it” dismisses the strip and drops you onto the live table.

Approval surfacing within the board: approvals are first-class table citizens. A waiting agent sorts to the top with a waiting badge, its Approve / Reject affordances rendered inline in the row’s action cell, and a one-tier diff micro-preview expandable in place. The header carries a live approval-queue chip (2 waiting) that, when clicked or via ⌘K → “next approval”, jumps the cursor to the top waiting row. No approval ever requires leaving the console.

Error surfacing within the board: errors sort above everything, render a red error badge, and put the failure’s first line into the one-line stdout cell. The header error chip mirrors the count. Selecting the row binds the detail pane to the full error / stack trace with Retry / Restart / Open terminal actions (mapping flow-map S5 Error state).

Push notifications (PWA): web-push for approval-needed and error/completion events deep-links into the console with the relevant row pre-selected (not to a standalone approval screen — V1’s whole premise is that the board is the approval surface). On a desktop where the console is already open, the notification is redundant with the live header chips; on mobile it routes into the collapsed-list degrade view (§17) with the row expanded. Notification preferences themselves live in S10 Settings (out of scope here).

10. Failure Recovery Behavior (mapped to flow-map failure paths)

How the Operator Console surfaces and recovers each flow-map failure. The design principle: failures are table-and-pane states, surfaced where the user is already looking (header chips + row badges + detail pane), never as modal interrupts that hide the fleet.

Cross-cutting failure principle for V1: because the fleet is never hidden behind a route or modal, all of these failures remain visible in aggregate (header chips) and per-agent (row badges) at the same time. The split-pane means the user can be deep in one agent’s terminal and still see a second agent error appear at the top of the table — a property no route-switching sibling (v2) preserves.

11. Page & Flow Changes vs. the Flow-Map Baseline

The flow-map lists S3, S4, S5, S6 as four distinct screens/routes and frames Mode A (structured) vs Mode B (terminal) as a user-selectable access mode (flow-map D2). V1 carries the brief’s confirmed reframe and restructures as follows:

1. S3 + S5 + S6 collapse onto ONE persistent route. There is no navigation from board to detail; the detail pane is a region of the console, bound by selection. The flow-map’s S3→S5/S6 “Downstream” handoff becomes an in-page pane-bind.
2. S5/S6 fold into one tool-adaptive detail pane. The flow-map’s separate “S5 Structured” and “S6 Terminal” screens — and its Mode A/B user toggle (D2) — are dropped. The detail pane’s primary rendering is determined by the tool’s integration pattern, not a user choice: terminal-primary (xterm.js/WS) for headless-CLI tools, structured for API-native tools. There is no “switch to terminal” mode button as a primary affordance (an escape-hatch terminal toggle survives only for structured/API tools that also expose a shell, as a secondary control — §14).
3. S4 changes from modal to inline. The flow-map’s centered modal-with-backdrop launch (S4) is replaced by an inline editable top-of-table row plus a ⌘K quick-launch palette. Launch happens in the table’s coordinate space, not over a dimmed board — preserving the never-lose-the-fleet principle even during launch.
4. S8 Async Recap demotes from screen to strip. The full-screen recap becomes a dismissible docked strip above the table (§9), because the live table already is the recap surface in this layout.
5. S7 Approval has no standalone screen. Approvals render inline in rows + in the detail pane; the flow-map’s dedicated S7 mobile-card is realized only in the mobile degrade view (§17), not on desktop.
6. Default sort retained but extended. Flow-map’s error > waiting > running > idle is kept as the default, extended with starting/paused/stopped/done tiers and made user-resortable by any column (the flow-map sort was fixed; V1 makes it a table affordance).

These are variation-level proposals consistent with the brief’s amendment note; they do not edit the approved flow-map doc.

12. Navigation Model

Single-route, selection-driven, keyboard-first. The console is effectively a one-page app for the monitoring-start surface.

• Primary nav = the row cursor. j/k or ↑/↓ move a highlighted cursor through table rows; Enter / click binds the cursor’s row to the detail pane. Esc releases selection back to the table.
• ⌘K command palette — the universal accelerator: New agent…, Jump to agent <name>, Filter by repo/tool/status, Sort by <column>, Next approval, Approve all clear, Stop agent <name>, Open settings. Fuzzy-matched. This is the fast path, layered over an always-visible board — never the only way to perceive or reach state (the v4 contrast).
• Header controls — approval-queue chip, error chip, status-count chips, filter/sort menu, repo filter, settings gear, “Open on Mobile / QR” button (for the cross-device handoff path), connection/tunnel status indicators.
• Within the detail pane — its own local nav: terminal focus (i / click to type) vs chrome focus; Tab cycles structured sub-sections (steps / file changes / approval); a small breadcrumb shows which agent is bound.
• No browser-back dependency. Because there is no route change on drill-in, back/forward are not part of the core loop (deep-links to a specific agent still set the initial selection for QR/push handoff).
• Focus discipline: a clear single keyboard-focus ring is always visible (table-row focus vs pane focus vs palette focus are visually distinct), because a keyboard-driven dense UI lives or dies on the user always knowing where their keystrokes land.

13. Screen-by-Screen Layout (regions & proportions)

All within one persistent route. Reference frame: desktop ≥1280px wide.

S3 — Console (the table) + persistent split-pane

┌──────────────────────────────────────────────────────────────────────────────┐
│ HEADER  gblock·console   [7 running ·2 waiting ·1 error]  [⌘K] [⟳tunnel] ⚙ │  ~52px
├──────────────────────────────────────────────────────────────────────────────┤
│ [filter: repo▾ tool▾ status▾]   sort: status▾            recap-strip(opt.) │  ~40px
├──────────────────────────────────────────┼────────────────────────────┤
│  + New Agent  (inline launch row)          │                              │
│ status·name·tool·repo·el·tok·act table       │   DETAIL PANE                │
│  ●E auth… aider api 12m 41k ⟳⏹          │   (folded, tool-adaptive)    │
│  ●W pay…  cc    web  4m 88k ✓✗         │   agent header / status      │
│  ●R index codex web  9m 120k ⏹  ◀───── binds selected row           │
│  ●R migr… sdk   api  2m 30k ⏹            │   PRIMARY RENDER:            │
│  ●I docs  cont… web 1h  9k ▶            │   terminal (xterm.js)        │
│  LEFT PANE ~55–62% width                     │   OR structured stream       │
│  table scrolls independently                 │   RIGHT ~38–45% width        │
│                                             │   footer: inject ▸ / stop    │
└──────────────────────────────────────────┼────────────────────────────┘

• Header (full width, ~52px): brand, live status-count chips (clickable filters), approval chip, ⌘K affordance, connection + tunnel indicators, settings gear, QR/Open-on-Mobile.
• Toolbar (~40px): filter dropdowns (repo / tool / status), sort selector, optional recap strip.
• Left pane — the table (~55–62% width):
  • Inline launch row pinned at the top (“+ New Agent”), becomes editable on activation (§14).
  • Columns (default): status badge · agent name · tool · repo · elapsed · token usage · one-line live stdout (flex, truncating, the widest data column) · action cell (inline approve/unblock/stop/retry icons). Token + stdout columns are the first to drop at narrower widths (§17).
  • Row height ~36–40px (dense; see §16). Status-tinted left edge bar per row.
  • Scrolls independently of the detail pane.
• Right pane — folded tool-adaptive detail (~38–45% width):
  • Top chrome: agent name, tool, repo, status badge, elapsed, token usage, and a secondary “Open full terminal” / “Pop out” control.
  • Primary render region (tool-adaptive — the fold):
    • Headless-CLI tools (Claude Code CLI, Codex, Aider, Continue, Cline, Copilot CLI, Augment): terminal-primary — a live xterm.js terminal over WebSocket fills the region; structured chrome (status, approval banner, file-change rail) wraps it. The terminal IS the native interface.
    • API-native tools (Claude Agent SDK): structured — parsed step stream, progress, file-change list, inline approval card. No terminal (none exists server-side).
    • The render choice is automatic from the agent’s tool, never a user mode toggle.
  • Footer: prompt-injection input ▸, stop / restart, and (for waiting agents) inline Approve / Reject.
• Split behavior: the divider is draggable (user can rebalance 50/50 ↔ 70/30); double-click snaps to preset. Esc with nothing selected collapses the detail pane and lets the table reclaim full width (max-density monitoring mode).

S4 — Start Agent (folded into the table, two ways in)

• Inline launch row (primary): the pinned top row’s cells transform into inputs — repo picker (auto-populated from GitHub OAuth), tool selector, prompt (expanding inline textarea), optional branch. ⌘Enter launches; Esc cancels. Validation: launch disabled until repo+tool+prompt set. On launch, the row converts to a real starting agent row in place. No backdrop, no modal — the fleet stays fully visible (the deliberate departure from the flow-map’s S4 modal).
• ⌘K quick-launch (accelerator): ⌘K → “New agent” opens a palette-style launcher with the same fields, fully keyboard-drivable, for users who never want to leave the keyboard. Same validation and outcome.
• S4 states honored (flow-map): Loading-repos (skeleton in repo picker, other fields disabled), Launching (spinner, fields disabled), Error (inline error + retry), Tool-unavailable (inline warning + “Install tool” → S10).

Folded S5/S6 Detail

Already described as the right pane above. Key point: there is no separate S5 vs S6 screen and no Mode A/B user toggle — one detail pane, rendering chosen by tool integration pattern. A secondary “Open full terminal” escape hatch exists for structured/API tools that happen to expose a shell, and a “Pop out” control can promote the pane to a focused full-width terminal for heavy interactive debugging (still the same route, the table temporarily yields width).

14. Key Components & Controls

• Fleet Table — virtualized (handles 5–12 comfortably, scales past it), sticky header, per-column sort, multi-facet filter, status-tier default sort, draggable + hideable columns (power affordance), keyboard row-cursor. Each cell type:
  • Status badge — colored dot + short label (E/W/R/I/starting/paused/done) + status-tinted row edge.
  • One-line stdout cell — live-tailing last stdout line, monospace, truncated with ellipsis; hover/focus shows a 3-line tooltip peek (mitigates the truncation risk, §20). The full stream lives in the detail pane.
  • Action cell — context-sensitive inline icons: Approve (✓) / Reject (✗) for waiting; Unblock (▸); Stop (⏹) for running; Retry (⟳) for error; Resume (▶) for paused/idle.
• Inline Launch Row — top-pinned editable row (repo / tool / prompt / branch); the in-table S4.
• ⌘K Command Palette — fuzzy launcher/jumper/filter/sorter/actioner (§12).
• Detail Pane — tool-adaptive container:
  • xterm.js terminal (CLI tools) over WebSocket, with copy/paste, search, and a clear keystroke-focus indicator.
  • Structured stream (API tools) — step list, progress bar, file-change rail, inline approval card.
  • Pane chrome — agent identity header, status, metrics, Pop-out, secondary Open-terminal (escape hatch), prompt-inject footer, stop/restart.
• Header chips — clickable status-count filters, approval-queue jump, error jump, tunnel/connection indicators.
• Recap strip — dismissible docked summary on threshold return (§9).
• Diff micro-preview — one-tier inline expansion in a waiting row for fast approve-without-drill-in.

15. Button & Link Behavior

• + New Agent (inline row / ⌘K): activates the launch row / palette. Disabled-to-active validation: enables Start only when repo + tool + prompt are set. ⌘Enter = Start, Esc = cancel.
• Approve (✓): inline on waiting rows and in the detail pane footer. Single-tier diff micro-preview expands on first press for confirmation; second press (or a then Enter) commits. Sends approval over the control socket; row resumes to running sub-second; auto-advances cursor to next waiting row.
• Reject (✗): opens an inline rejection-reason input in the row’s expanded tier; submit sends feedback to the agent.
• Unblock / Resume (▸ / ▶): resumes a paused/idle agent; for paused — credential/auth rows it routes to the credential fix first.
• Stop (⏹): guarded — single click arms (icon turns red, “click again to stop”), second click within 3s confirms; x key follows the same arm-confirm pattern. Prevents fat-finger fleet damage in a dense table.
• Retry / Restart (⟳): re-runs a crashed/errored agent with the same prompt; Restart from the detail pane allows an adjusted prompt.
• Status-count chips (header): click = filter the table to that status; click again = clear. error/waiting chips also support “jump to first” via ⌘K equivalents.
• Pop-out / Open full terminal: promotes the detail pane to full-width focused terminal (same route, table yields); Esc restores the split.
• Row click vs row action-cell click: clicking anywhere in a row except the action cell selects it into the pane; clicking an action icon performs the action without changing selection — so triage clicks never disturb a deep-work selection.
• QR / Open on Mobile (header): generates the short-lived pre-authenticated deep link encoding the current selection, for cross-device handoff.
• Re-authorize GitHub / Update credential (failure banners): route to OAuth / S10; on success, affected rows auto-resume.

All destructive or fleet-affecting actions are guarded or reversible; all resume actions are non-destructive and preserve session state.

16. Spatial Density, Sizing, Hierarchy

V1 is the explicit high-density end of the posture axis — density is the thesis, tuned, not careless.

• Row height ~36–40px, ~13–14px base text, monospace for stdout/tool/repo/token cells (NOC legibility), proportional for names. 12 rows fit in a single desktop viewport without scroll.
• Column hierarchy (visual weight, high→low): status badge (color, leftmost, the eye’s anchor) → agent name (bold) → one-line stdout (the live signal, widest flex) → repo/tool (muted, monospace) → elapsed/token (smallest, right-aligned numerics) → action cell (icon-only, reveal-on-row-focus to reduce resting clutter, always-visible for error/waiting).
• Color as primary status channel (against the dark house palette --bg:#1a1a2e --card:#16213e --border:#2a2a4a --accent:#4dabf7 --text:#e0e0e0 --muted:#8b8fa3): error = red, waiting = amber, running = green/accent, idle = muted grey, paused = amber-muted, done = blue-muted. Status-tinted left row-edge gives a scannable color rail down the table.
• Split proportion defaults ~58/42 (table/detail), draggable, with a max-density mode (table full width, pane collapsed via Esc).
• Whitespace is intentionally scarce in the table and intentionally generous in the detail pane — the contrast (dense fleet ↔ focused single agent) reinforces the two-layer mental model spatially.
• Hierarchy rule: the user’s eye should land on red/amber rows at the top first, then the selected row’s highlight, then the detail pane. Sort + color do the triage work before any reading happens.

17. Responsive Behavior at 3 Breakpoints

Mobile is V1’s deliberate degrade case (the design center is desktop-dense; v5 owns mobile-first).

• Desktop > 1024px (design center): full split-pane, full column set (status · name · tool · repo · elapsed · token · stdout · actions), draggable divider. At ≥1440px the stdout column widens and an optional second metrics column (cost / message count) can be enabled. This is where V1 is meant to be lived in.
• Tablet ≤ 1024px: split-pane persists but detail pane goes overlay-on-demand rather than always-side-by-side, OR the split shifts to ~65/35 with a narrower detail pane. Columns shed in priority order: token usage drops first, then elapsed compresses to relative (“9m”), stdout truncates harder. Inline launch row stays. ⌘K remains. Still fundamentally a table.
• Mobile ≤ 640px (degrade): the table collapses to a compact stacked list — one card-ish list item per agent showing status badge + name + one-line stdout + a single primary inline action (the brief’s prescribed collapse). Columns become a two-line stacked cell. The split-pane breaks: selecting an agent pushes a full-screen detail sheet (the only place V1 uses route-like navigation, because side-by-side is impossible on a phone). On mobile, the folded detail’s terminal is read-mostly with an “Open on desktop / scan QR” handoff for heavy interactive terminal work (honoring the terminal-latency open question — a phone is a poor place to type into a low-latency-critical terminal). Approvals on mobile render as the flow-map’s large-tap-target S7-style cards. This degrade is honest: V1 on a phone is a monitoring + approve tool, not a deep-work tool — and that’s fine, because that posture is exactly what v5 is purpose-built for, and the QR handoff bridges to a desktop where V1 shines.

18. Visual Tone

NOC / server-monitoring console. Dark, dense, instrument-panel calm-under-load. Monospace data, color-coded status as the dominant signal, tight gridlines, minimal chrome, no decorative illustration once the fleet is live (illustration appears only in the empty state). The aesthetic reference set: htop / k9s / btop / Grafana / a trading terminal — tools that pack maximum signal into a glance and reward a trained eye. Motion is restrained: rows re-sort with a quick settle, they don’t fly between regions (the deliberate anti-v3 choice); status badges may pulse subtly when waiting. The dark house palette is the baseline; status colors are the accent vocabulary. Confidence over friendliness — this screen should feel like a cockpit you’ve mastered, not a dashboard you’re being onboarded to.

19. Strengths

• Maximum fleet glanceability — all 5–12 agents and their full status vocabulary visible on one screen with zero scrolling or navigation; the densest possible read of the fleet.
• Drill-in never loses the fleet — the persistent split-pane is the only sibling layout where you work one agent and watch the other eleven simultaneously. A second agent erroring while you’re deep in a terminal is still visible.
• Fastest triage and parallel-sprint launch — sort + color + inline actions + ⌘K make round-robin approvals and fanning out agents #2/#3 (Path C) extremely fast for a trained user; no modal, no route, no context loss.
• Keyboard-native end to end — j/k/Enter/a/u/x/n/⌘K make the whole loop mouse-optional, matching the power-user persona’s reflexes.
• Comparison across agents is trivial — tabular columns make “which agent is burning the most tokens / running longest / stuck” a single sort, which cards (v2) and feeds (v5) can’t do.
• Failures stay aggregate + per-agent simultaneously — header chips and row badges keep the whole fleet’s health legible even mid-deep-work.

20. Risks & Failure Modes (of the design)

• Truncated rich stdout — a one-line cell cannot convey a multi-line tool transcript; nuance is lost at the table tier. Mitigations: hover/focus 3-line peek tooltip; the full stream is always one selection away in the detail pane; stdout is the widest column. Still the sharpest tradeoff vs v2’s roomy card previews. (Also gated by the brief’s stdout-parsing-reliability open question — if parsing is unreliable, even the one-liner is noisy; V1 leans on the raw last-line as a fallback rather than promising parsed status.)
• Intimidating / steep — a NOC table reads as cockpit chrome to a newcomer and can feel hostile at 1–3 agents. Mitigations: suppressed-chrome empty state, progressive disclosure of sort/filter machinery, ⌘K hinting. But it will never be the welcoming option — that’s v2’s job, and that division of labor is intentional.
• Weak on mobile — the table genuinely doesn’t belong on a phone; the collapse is a degrade, deep-work terminal is read-mostly. Mitigation: honest QR/desktop handoff; lean on v5 for the phone-up moment. This is an accepted, scoped weakness, not a bug.
• Terminal latency in a side pane — the folded detail’s xterm.js still depends on sub-100ms echo over the tunnel (open question #1); a narrow side pane makes a laggy terminal feel even more cramped. Mitigation: Pop-out to full width for heavy interactive sessions; structured-first for API tools sidesteps it.
• Density fatigue / misclick risk — packed rows + inline destructive actions invite fat-fingers. Mitigation: guarded Stop (arm-confirm), action-cell clicks don’t change selection, reveal-on-focus action icons reduce resting clutter.
• Color-only status is an accessibility risk — color-coding is the dominant channel. Mitigation: every badge pairs color with a text/letter label and the status word; never color alone.
• Re-sort jumpiness — rows reordering as status changes can move a row out from under the cursor mid-action. Mitigation: the selected row stays bound to the pane regardless of its sort position; sort settles are debounced.

21. Implementation Complexity

Medium (matches the brief’s rating). Heavier than v2 (the card-grid control), lighter than v3 (kanban drag/animation/column state machine).

What drives the cost:

• Virtualized, sortable, multi-filter, keyboard-navigable data table with live per-row WebSocket updates and a stable selection that survives re-sort — the central non-trivial component. Off-the-shelf table libs help but the live-update + keyboard-cursor + stable-selection combination needs care.
• Persistent split-pane with draggable/collapsible divider and independent scroll regions — moderate.
• Tool-adaptive folded detail — must host both an xterm.js/WebSocket terminal (CLI tools) and a structured stream renderer (API tools), switching on tool type. The terminal + WS transport is the same cost every sibling pays; V1 adds the constraint of making it work well in a narrow pane (pop-out logic).
• ⌘K command palette with fuzzy match over launch/jump/filter/sort/action verbs — moderate, well-trodden.
• Inline launch row as an in-table editable state machine (idle → editing → validating → launching → real-row) — fiddlier than a plain modal but contained.
• Three-breakpoint responsive including the full table→stacked-list→full-screen-sheet mobile degrade — non-trivial but the mobile path is intentionally a simpler subset.

No multi-user, sharing, or permissions code (N/A) — that subtracts real complexity other product types would carry.

22. Prototype Scope (lightweight, evaluable build)

A lightweight prototype must include enough to let a solo evaluator run the §5 loop and feel the density tradeoff. Minimum:

1. Populated fleet table with ~8–10 mock agents spanning every status (error / waiting / running / idle / paused / done / starting), default error > waiting > running > idle sort, at least sort-by-status and sort-by-elapsed working, and a status/repo filter.
2. Live-ish one-line stdout per row (mock tail loop is fine) + status badges with color + text labels + status-tinted row edges.
3. Keyboard nav — j/k/Enter row cursor + selection, Esc deselect, ⌘K palette (at least New-agent + Jump-to + Filter verbs).
4. Persistent split-pane with a working selection bind: selecting a row renders the detail pane while the table stays visible and keeps updating. This simultaneity is the single most important thing to demonstrate — it’s V1’s whole thesis.
5. Tool-adaptive detail — at least two mock agents: one CLI-type rendering a (mock or real) xterm.js terminal, one API-type rendering a structured step stream. Prove the auto-render-by-tool with no user toggle.
6. Inline launch row producing a new starting row (mock launch) + ⌘K quick-launch equivalent.
7. Inline actions — Approve/Reject on a waiting row (with one-tier diff peek), guarded Stop, Retry on an error row; action-cell clicks must not disturb the current pane selection.
8. At least two failure surfaces rendered as table/pane states: backend-unreachable banner + table dim, and an agent-crash row with retry budget — to prove failures stay visible without hiding the fleet.
9. Responsive proof — resize to ≤640px and show the table collapse to the stacked list + full-screen detail sheet (the honest degrade).

Mock WebSocket/stdout and mock approvals are acceptable; the evaluation target is the interaction model and density feel, not backend fidelity.

23. Readiness Signal — what makes this branch ready for /ui-interview

This branch is ready to advance to /ui-interview [v1-operator-console] when, during /uat --variant-evaluation against its siblings, the solo evaluator gives a clear signal such as:

• Task-based: triaging a 10-agent fleet (sort errors up, approve the clear ones, drill into one crash, launch a parallel agent) is measurably faster and lower-friction in V1 than in v2/v5, and the evaluator explicitly values keeping the whole fleet visible while working a single agent (the split-pane simultaneity) — i.e. they used it and missed it elsewhere.
• Gut-check: the evaluator says some version of “this is how I want to run my fleet from my desktop — the density is a feature, not a wall,” and is willing to accept the mobile-as-degrade tradeoff (reaching for the QR/desktop handoff rather than wanting V1 itself to be phone-good).
• Negative-confirm: the intimidation/density-fatigue risk (§20) did not dominate the evaluator’s reaction for the target power-user posture; the empty-state ramp and ⌘K hinting were enough.

If instead the evaluator wants V1’s split-pane fleet-visibility but v2’s card richness, or v5’s mobile posture, that is a consolidation signal (feed /consolidate-variations), not a ready-for-interview signal for V1 standalone. Readiness for /ui-interview specifically means: the Operator Console’s dense-desktop, split-pane, inline-action model is the chosen direction for the monitoring-start surface and is ready to be pinned down visually.

1. Name & Thesis

Card Mosaic. A familiar SaaS dashboard: the fleet is a responsive grid of rich agent cards, each a self-contained status tile with a live stdout preview. You scan the mosaic, launch from a modal, and drill into a single agent by navigating to a full-page detail route. The thesis is zero learning curve — anyone who has used Vercel, Railway, GitHub Actions, or a CI dashboard already knows how to read this board. It deliberately trades cleverness for legibility so it can serve as the control the other four concepts must beat.

Design center of gravity: glanceability per agent. Each card carries enough rich context (badge, tool, repo, elapsed, tokens, multi-line stdout) that the board answers “what is each agent doing right now?” without a drill-in. The cost — accepted on purpose — is fleet density: cards are large, so 12 agents scroll.

2. Parent User Flow & Branch Relationship

This variation realizes the monitoring-start branch: Happy Path steps 3–6 (S3 Board → S4 Start → S3 new card → S5/S6 Interact) plus Path C “Parallel Sprint” (launch agent #2, #3; monitor all; round-robin approvals).

It is the baseline/control. Where the brief’s four axes are spread across siblings, V2 takes the flow-map-native position on every axis:

Because it tracks the flow-map most literally, V2 introduces the fewest net-new interaction concepts. The one deliberate divergence from the approved doc is the folded tool-adaptive detail (see §11) — a constraint carried by every variation per the brief’s confirmed reframe, not unique to V2.

3. Target User Fit

The balanced default Agent Conductor. Specifically:

• A solo dev running 5–12 agents across 1–3 repos who works across devices (desk + couch + phone) and wants one mental model that survives the switch.
• Someone who values recognition over recall — would rather see a labeled card than memorize a command palette or a column convention.
• A user whose first reaction to a new tool is “show me the dashboard,” not “show me the shortcuts.”

Best-fit summary: the persona before they have strong opinions. V2 is what you reach for when you don’t yet know whether you’re a power-keyboard user (→ V1/V4), a triage-first thinker (→ V3), or a phone-up checker (→ V5). It degrades gracefully to 1-column mobile, so it is never wrong on any device, just never maximally optimized for one.

Weak fit: a max-density NOC operator babysitting 12 agents on a single 27" screen (cards waste vertical space — that’s V1’s job).

4. Onboarding / Activation Model

Entry into this surface is post-setup: Path A (onboarding) provisions the workspace and redirects to S3 with an empty board. V2 owns the empty → first-agent moment on the board.

Empty state (S3 Empty):

• Centered illustration/glyph + headline “Start your first agent.”
• A single prominent Start Agent button (primary accent) — this is the only real CTA; nothing else competes.
• Below it, a one-line “quick-start” link → a 3-step explainer (pick repo → pick tool → describe the task) that can open the S4 modal pre-focused on the repo picker.
• Secondary, muted: “Open settings” (for users who arrived without a tool installed).
• Approval-queue badge and diff/review affordances are hidden in the empty state (per S3 matrix: “Approval/diff actions hidden”).

Activation = the first card appears. When the user completes the S4 modal, a card animates into the grid with a “starting” badge and flips to “running” within seconds, its stdout preview beginning to stream. That first live preview is the aha for this surface — the user sees the agent working without any SSH/tmux ceremony. The empty illustration is replaced by a real 1-card mosaic, which implicitly teaches the grid model.

Progressive disclosure: the modal’s “optional branch” field stays collapsed under a “More options” toggle on first run, so the first launch is the minimal repo + tool + prompt.

5. Typical Workflow Sequence

Parallel Sprint (Path C), the representative flow:

1. Open PWA → lands on S3 Agent Board (returning session). Mosaic renders all current agents, sorted error > waiting > running > idle. Header shows approval-queue badge.
2. Scan the mosaic. Each card’s badge + stdout preview answers “what’s happening” at a glance; no drill-in required for routine monitoring.
3. Click Start Agent (header button) → S4 modal opens over the dimmed board.
4. In the modal: pick repo (dropdown), pick tool (dropdown), type the prompt (textarea), optionally expand branch. Click Start Agent.
5. Modal closes; a new “starting” card appears in the grid, transitions to “running,” stdout begins streaming. (Happy Path step 5.)
6. Repeat 3–5 for agent #2 and #3 (different repos/branches). Board now shows 3+ live cards.
7. An agent hits a decision point → its card flips to a waiting badge, pulsates subtly, and re-sorts toward the top; the header approval-queue count increments.
8. Click the waiting card → navigate to the full-page detail route for that agent. The detail is folded + tool-adaptive: terminal-primary for CLI tools (xterm.js), or structured-primary for API-native tools. Handle the inline approval here.
9. Click Back to Board → return to S3 (board re-reads server-canonical state; the card is now “running” again).
10. Round-robin steps 7–9 across agents as approvals arrive.
11. When agents finish, cards show a completion summary; a Review diffs CTA surfaces (handoff to S9, out of this branch’s deep scope but linked).

6. Progression Model — and How It Differs From the 4 Siblings

How the user advances in V2: by navigation and recognition. The orchestration layer (mosaic) and the deep-work layer (detail) are two distinct places. You progress by clicking a card to travel to its detail route, and you back out to return to the board. State is server-canonical, so the round trip is lossless — but it is a round trip: the board is replaced by the detail page, not held alongside it. New work enters via the modal, which is a temporary overlay on top of wherever you are.

This is the closest-to-baseline progression: a classic two-place dashboard → detail pattern with a modal for creation. Explicit contrast:

• vs V1 Operator Console — V1 keeps the fleet and the detail on screen at once via a persistent left-board / right-detail split-pane; you progress by selecting rows without leaving the fleet. V2 instead leaves the board to enter detail (full-page route). V1 trades V2’s per-agent richness for fleet-wide density (one dense row per agent). V2 is more legible per agent; V1 never loses fleet context.
• vs V3 Kanban Pipeline — V3 makes status the spatial primary: cards physically move between lifecycle columns and detail is a drawer that slides over a board that stays behind. You progress by watching cards flow and pulling triage items out of the Waiting/Error columns. V2’s cards don’t move by status (they re-sort within one grid) and detail replaces the board rather than overlaying it. V2 is calmer (no card motion); V3 surfaces bottlenecks spatially.
• vs V4 Command-First — V4 makes the verb primary: you progress by typing into a palette (⌘K) to launch/filter/jump/approve, and detail is a focus mode with the board as a back-stack. V2 progresses by clicking visible affordances (button, card), not typing. V2 is higher-discoverability and slower for an expert; V4 is faster for a keyboard native and quieter on glance.
• vs V5 Glanceable Stream — V5 is phone-up: a prioritized vertical feed with swipe actions and template-based quick-start, detail as a full-screen sheet. V2 progresses the same on phone and desktop (responsive grid both ways) rather than optimizing the phone reading order. V5 wins the couch/phone aha; V2 wins device-neutrality.

One-line positioning: every sibling deviates from the dashboard mental model on exactly one axis to test a hypothesis; V2 holds all four axes at the flow-map default so those deviations have something to be measured against.

7. Sharing & Collaboration Model

N/A — single-user personal workstation. Per the flow-map’s explicit non-goals (“Multi-tenant / team features (personal-workstation scope only)”) and the brief’s locked constraint, this product has exactly one user — the Agent Conductor who owns the managed VM and their own GitHub OAuth + model subscriptions. There are no shared boards, no invited collaborators, no co-viewing, no comments, and no handoff-to-another-person flow. The only “handoff” in scope is the same user moving between their own devices (cross-device continuity), which is server-canonical state, not collaboration. No sharing UI is designed.

8. Permissions Model

N/A — single-user personal workstation. There are no roles, no per-resource ACLs, no seat management, and no permission tiers, because there is exactly one principal. The only authorization in the system is external: GitHub OAuth grants the single user repo read/write + PR scopes so their agents can operate on their repos (flow-map S1), and the user’s own model keys/subscriptions authorize model traffic (BYO-client; the board never proxies). Those are credentials the user holds, not in-app permissions V2 grants to others. No permissions surface is designed; failures of those external credentials are handled as recovery paths (§10), not as a permissions UI.

9. Return-Use & Notification Model

V2 is a return-heavy surface (the Conductor checks in repeatedly across a day and across devices). Return mechanics:

• Re-entry lands on S3. A returning session with valid state opens straight to the mosaic at current server-canonical state — no reconnection ceremony, no stale data (flow-map handoff: “state is server-canonical”).
• At-a-glance return read: sort (error > waiting > running > idle) + the header approval-queue badge mean the first thing the eye lands on is whatever needs the user. Waiting cards pulsate; error cards show a red badge + error summary line.
• Recap on long absence: if the device-switch/time-gap threshold is exceeded (D7), an S8 Async Recap is offered before the board — a vertical timeline of what happened while away (completed, pending approvals, errors, PRs). Dismiss → S3. V2 treats recap as an interstitial over the mosaic, consistent with the modal-and-route pattern, not a permanent board region.
• Notifications: Web Push via the PWA service worker. An approval or completion fires a push to all connected devices; tapping the push deep-links into the relevant agent’s detail route (or to S3 if the deep link can’t resolve). This is the engine of the “closed laptop, checked from phone” loop, even though the approval branch itself is owned by a sibling flow (approval).
• PWA install is offered on first mobile visit (per Path F) to enable push + home-screen re-entry.
• Push reliability on mobile (esp. iOS Safari) is a known open question (flow-map Open Q #3); V2 does not assume push is guaranteed — the board’s sort + badge make the surface usable as a pull channel even if a push is missed.

10. Failure Recovery Behavior

Mapped to the flow-map Failure & Recovery table and the per-screen matrices:

S4 modal failures (launch fails / tool unavailable): inline error in the modal with a Retry; if the selected tool isn’t installed in the workspace, a warning with an Install tool link to S10 and Start disabled until a valid tool is chosen (S4 matrix).

Recovery design principle for V2: failures are expressed on the card (badge + summary + re-sort to top) so the board itself is the recovery queue — no separate error console. Deep remediation happens by clicking through to the folded detail.

11. Page & Flow Changes vs. the Flow-Map Baseline

V2 is intentionally the minimal-divergence variation. Tracking:

• S3 Agent Board — tracks the flow-map low-fi notes essentially verbatim: responsive card grid (2–3 cols desktop / 1 col mobile), card fields (name, status badge, tool, repo, elapsed, stdout preview), sort order, empty state with “Start your first agent,” and the connection-lost banner. Addition: cards also surface token usage (Happy Path step 3 lists it) and expand the stdout preview from one line to one-to-multi-line (see §13) — a richness bump, not a structural change.
• S4 Start Agent — tracks the flow-map exactly: centered modal with backdrop; repo / tool / prompt / optional-branch fields; Start primary + Cancel secondary; validation gates Start. No divergence.
• S5/S6 Detail — THE deliberate divergence. The flow-map lists S5 (Structured) and S6 (Terminal) as two screens with Mode A/B as a user choice (D2, “Open Terminal” toggle). Per the brief’s confirmed reframe (load-bearing, applies to every variation), V2 folds these into ONE detail route whose primary rendering is tool-adaptive:
  • CLI tools (Claude Code CLI, Codex CLI, Cursor worker, Aider, Continue, Cline, Copilot CLI, Augment) → terminal-primary (xterm.js over WebSocket) wrapped in structured chrome (header: name/tool/repo/status/elapsed; side rail: approval count + quick-approve; file-change strip).
  • API-native tools (Claude Agent SDK) → structured-primary (parsed activity stream, progress, file-change list, inline approval, prompt-injection footer) — no terminal, because there is no terminal to attach to.
  There is no Mode A/B user toggle. The folding is determined by the tool’s integration pattern, not selected by the user.
• Mode C / code-server (IDE) — out of scope for V2 (flow-map Open Q #4, brief bounding question). V2 makes no IDE affordance; it does not argue the case. The “drop to terminal” escape hatch for CLI tools covers the manual-intervention need without an IDE.

Net: two screens (S3, S4) match the baseline; the detail folds two baseline screens into one tool-adaptive route. This should propagate to the flow-map as an amendment, not a silent edit (per the brief).

12. Navigation Model

Place-based, route-driven — the canonical SaaS-dashboard nav:

• Persistent header (present on board; condensed on detail): app name/logo, approval-queue badge (count), settings gear → S10, and a QR / “Open on Mobile” button (Path F).
• S3 board is the home/hub. All deep paths originate here.
• Card → detail is a full-page navigation (URL changes to /agents/:id). The board is unmounted; detail is the active view. This is the defining nav choice of V2 and the source of its main risk (board context drops on the round trip — §20).
• Detail → board via an explicit Back to Board control (and browser back). Because state is server-canonical, returning re-reads live state — no stale board.
• Start Agent is a modal overlay, not a route: it stacks on top of the current view (board or detail) and dismisses back to it. Launching never navigates away.
• Deep links resolve directly to a route: a push/QR can open /agents/:id (detail), /approvals context, or / (board). Falls back to board if a deep link can’t resolve.
• Recap (S8) appears as an interstitial over the board on long-absence re-entry, then dismisses to the board.

Routing surface (illustrative): / board · /agents/:id folded detail · S4 and S8 as overlays/interstitials over whatever route is active · /settings (S10).

13. Screen-by-Screen Layout (Regions & Proportions)

S3 — Agent Board (mosaic)

• Header (top, ~56–64px tall, full width, sticky): left = app name; right cluster = approval-queue badge, “Open on Mobile”/QR, settings gear. A secondary row or right-aligned primary button = Start Agent.
• Connection banner (conditional, directly under header, full width): reconnecting state.
• Primary content = the mosaic (fills the rest): responsive grid of cards.
  • Desktop >1024: 3 columns; tablet ≤1024: 2 columns; mobile ≤640: 1 column.
  • Gutters generous (cards breathe — this is the density tradeoff vs V1).
• Card (the core component), regions top→bottom:
  1. Top row: agent name (left) + status badge (right; color-coded: error/red, waiting/amber, running/green, idle/grey).
  2. Meta row: tool name · repo (· branch if set) — small/muted.
  3. Metrics row: elapsed time · token usage — small/muted, right-aligned.
  4. stdout preview region (the distinctive area, ~3–5 lines, monospace): live one-to-multi-line tail of the agent’s output, auto-scrolling. This is what makes a card “rich” and is V2’s signature. Truncates with a fade at the bottom.
  5. (Conditional) error/completion strip: one-line error summary, or “completed — Review diffs →” on finish.

  Whole card is the click target → detail route. Status drives a subtle left-edge accent and (for waiting) a gentle pulse.

• Empty state replaces the mosaic: centered illustration + “Start your first agent” CTA + quick-start link.

S4 — Start Agent (modal overlay)

• Backdrop: dims the board (~50% scrim), click-to-cancel.
• Modal (centered, ~480–560px wide desktop; near-full-width sheet on mobile):
  • Title: “Start Agent.”
  • Repo picker (dropdown, auto-populated from GitHub OAuth; skeleton while loading).
  • Tool selector (dropdown).
  • Prompt (textarea, the tallest field, ~4–6 rows).
  • “More options” toggle → optional branch field.
  • Footer actions: Start Agent (primary, right; disabled until repo+tool+prompt set) · Cancel (secondary, left).
  • Inline error region above the footer for launch/tool-unavailable failures.

S5/S6 — Folded Agent Detail (full-page route)

• Top bar (full width): Back to Board (left); agent name · tool · repo · status badge · elapsed/session duration (center/left); stop / restart controls (right).
• Primary region (fills the page):
  • CLI tools → terminal-primary: a large xterm.js terminal fills the main area (≈70–80% width on desktop). It is the live, interactive interface.
  • API-native tools → structured-primary: the main area is the parsed activity stream (steps, progress indicator, file-change list) in the same footprint.
• Side rail (right, ~20–30% desktop; collapses below on mobile): approval-queue count + quick-approve button when pending; file-change summary; (for the structured view) the same file-change list lives here or inline.
• Inline approval: when the agent is waiting, an approval card appears in-flow (over the terminal as an overlay/badge for CLI; inline in the stream for structured) — approve / reject / modify / defer.
• Footer: prompt-injection textarea + send (both renderings); for CLI this writes to the session, for structured it injects into the agent.

Proportions summary: board = full-bleed grid; modal = centered ~520px card; detail = top bar + dominant primary region + a slim right rail.

14. Key Components & Controls

• Agent Card — the signature component: badge + meta + metrics + live stdout preview + conditional error/completion strip. Whole-card click target. Live-updating via WebSocket.
• Status Badge — error / waiting / running / idle / starting / completed; drives color, sort priority, and pulse.
• Live stdout Preview — monospace auto-scrolling tail (3–5 lines) inside each card. Reliability is bounded by the Multica-style stdout-parsing open question (§20); preview is best-effort tail, not a guaranteed structured parse.
• Start Agent button (header) + Start Agent modal (repo dropdown, tool dropdown, prompt textarea, optional branch, Start/Cancel).
• Approval-queue badge (header) + inline approval card (detail) + quick-approve (detail side rail).
• xterm.js terminal (CLI detail) / parsed activity stream (API-native detail) — the folded tool-adaptive primary.
• prompt-injection textarea (detail footer).
• stop / restart / retry controls (card error strip + detail top bar).
• Connection/recovery banner (board) + reconnecting overlay (detail).
• Back to Board control (detail top bar).
• QR / Open on Mobile button (header) and PWA install prompt (first mobile visit).
• Async Recap interstitial (S8 timeline on long-absence re-entry).

Sort/filter: default sort error > waiting > running > idle. Filtering is deliberately light in V2 (a simple status filter / repo filter chip row is the most it should add) — heavy filtering is V1’s territory; V2 leans on big legible cards instead.

15. Button & Link Behavior

• Start Agent (header/empty-state) → opens S4 modal over the current view; does not navigate. Disabled never (always available unless connection lost, where it’s disabled with the banner).
• Start Agent (modal footer) → fires the launch REST call; button shows a spinner, fields disable, “Starting agent…”; on success the modal closes and a starting card appears; on failure an inline error + Retry. Disabled until repo + tool + prompt are all set.
• Cancel (modal) → closes modal, returns to underlying view, no side effects.
• Agent Card (whole card) → navigates to /agents/:id (full-page detail). Hover = subtle lift/accent.
• “Review diffs →” (completion strip) → routes to S9 diff review (linked, sibling-scope).
• Retry (error strip / detail) → re-launches the agent with the same prompt; card → starting.
• Back to Board (detail) → navigates to /; board re-reads live state.
• Quick-approve / Approve / Reject / Modify / Defer (detail) → posts the approval to the agent; agent resumes sub-second; UI advances to next approval or back to streaming.
• Approval-queue badge (header) → routes to the highest-priority waiting agent’s detail.
• Settings gear → S10. QR / Open on Mobile → shows QR overlay (short-lived pre-authed deep link).
• Tool-unavailable “Install tool” link (modal) → S10, with the modal’s selection remembered.
• Browser back is a first-class citizen (routes, not just modals) — back from detail returns to board.

All destructive/irreversible actions (stop, reject) get a confirmation affordance; launching and approving do not (they’re the happy path and reversible enough).

16. Spatial Density, Sizing, Hierarchy

• Density: comfortable, not dense. V2 deliberately sits in the middle of the density axis — cards are large and well-spaced so each is independently legible and tappable. This is the explicit tradeoff: it costs fleet density (12 agents scroll) to buy per-agent glanceability and co-equal touch usability.
• Card size: roomy enough for a 3–5-line stdout preview without crowding the metadata — target ~ 220–280px tall on desktop. Min tap target for any in-card control ≥ 44px (mobile).
• Hierarchy within a card: status badge + name (primary) → stdout preview (secondary, the “what’s happening”) → meta/metrics (tertiary, muted). Color is reserved almost entirely for status; everything else is grayscale so the badge carries the signal.
• Board hierarchy: sort + pulse + red badges pull the eye to what needs action; the header approval-badge is the single global alarm.
• Detail hierarchy: the primary region (terminal or stream) dominates; chrome (top bar, side rail) is quiet so the live interface owns attention.
• Type scale: card name ~15–16px; meta/metrics ~12–13px muted; stdout preview ~12px monospace. Generous line-height in the preview for scannability.
• Color: dark house palette (--bg:#1a1a2e; --card:#16213e; --border:#2a2a4a; --accent:#4dabf7; --text:#e0e0e0; --muted:#8b8fa3). Status colors layered on top: green/running, amber/waiting, red/error, grey/idle. Accent (#4dabf7) reserved for the primary CTA and links. Terminal background slightly darker than card to read as a console.

17. Responsive Behavior at 3 Breakpoints

Mobile ≤ 640px (1 column):

• Mosaic = single-column stack of full-width cards; stdout preview may trim to ~2–3 lines.
• Header condenses; Start Agent may become a sticky bottom-right FAB or a full-width button.
• S4 modal becomes a near-full-screen sheet; fields stack; Start/Cancel pinned to a bottom action bar; large tap targets.
• Detail: top bar compresses (Back as a chevron); side rail collapses below the primary region (terminal/stream full-width). For CLI tools the terminal is read-mostly with an “open on desktop” hint for heavy typing (terminal latency + soft-keyboard ergonomics are the bounding constraints — V2 does not pretend phone terminal typing is great).
• Recap and QR render as full-screen sheets.

Tablet ≤ 1024px (2 columns):

• Mosaic = 2-column grid; cards keep full richness (3–5-line preview).
• Modal centered, ~480–520px.
• Detail: terminal/stream ~70% with the side rail visible at ~30% (may be collapsible).

Desktop > 1024px (3 columns):

• Mosaic = 3-column grid, generous gutters; full card richness.
• Modal centered ~520–560px over a dimmed board.
• Detail: terminal/stream dominant (~75–80%) + persistent right rail (~20–25%); top bar full.
• At very large widths the grid can grow to a capped max (e.g., 3–4 cols) rather than sprawling — V2 caps columns to keep cards readable rather than chasing density.

Co-equal posture means no breakpoint is the “real” one — the same components reflow; the phone gets a usable read-and-approve experience, the desktop gets comfortable multi-agent monitoring, neither is the privileged target. (Contrast: V1 privileges desktop, V5 privileges phone.)

18. Visual Tone

Familiar, trustworthy, boringly competent — on purpose. It should read like a polished deploy/CI dashboard (Vercel/Railway/Render lineage) so a new user feels instant fluency. Dark house palette; calm grayscale chrome with status color as the only loud element; soft card elevation; restrained motion (cards fade in on launch, waiting cards pulse gently, stdout scrolls smoothly — no gratuitous animation). The terminal in detail reads as a real console (monospace, darker bg). The overall message: “this is the safe, legible way to watch your fleet” — which is exactly the control’s job.

19. Strengths

• Lowest learning curve in the set — universal dashboard pattern; recognition over recall.
• Richest per-agent glance — badge + tool + repo + elapsed + tokens + multi-line live stdout means routine monitoring rarely needs a drill-in.
• Truly device-neutral — one model that degrades cleanly to 1-column mobile; never wrong on any device.
• Maps almost 1:1 to the approved flow-map — fewest net-new concepts, so it’s the cleanest control to measure the other four against.
• Failures live on the card — the sorted board doubles as the recovery/triage queue; no separate error console.
• Lowest build risk / fastest to ship (see §21) — frees evaluation budget for the riskier siblings.
• Modal launch is non-disruptive — launching never costs you your place.

20. Risks & Failure Modes

• Cards waste space at scale. At 10–12 agents the comfortable cards scroll significantly; there’s no single-screen overview. (This is the explicit reason V1’s dense table exists.) Mitigation: column cap + sort-to-top for actionable agents, but the ceiling is real.
• Route-switch drops board context. Drilling into an agent unmounts the board; the user loses the at-a-glance fleet view while in detail and must travel back. (V1’s split-pane and V3’s drawer-over-board exist precisely to avoid this.) Mitigation: fast back, lossless server state, deep links — but the round-trip cost is inherent to V2’s choice.
• stdout-preview reliability is bounded. The card’s live preview leans on Multica-style stdout parsing/tailing, whose generalization across CLI tools is an open question (flow-map Open Q #2). If parsing is noisy, the previews become reassuring-but-misleading. Mitigation: treat preview as a raw best-effort tail, not a structured promise; structured fields (badge/elapsed/tokens) come from control-plane signals, not stdout.
• Terminal latency in folded CLI detail. Sub-100ms keystroke echo over the tunnel is unproven (Open Q #1); if it’s laggy, the terminal-primary detail for CLI tools feels bad, especially on mobile. Mitigation: phone detail is read-mostly with desktop handoff; this is intrinsic to CLI tools, not a V2-specific flaw.
• “Generic” risk. Being the familiar control means it may underwhelm a power user who wants density (V1) or speed (V4) — it can lose an evaluation by being merely fine.
• Modal launch friction at high volume. Repeated repo/tool re-selection in the modal is slower than a template/duplicate quick-start (V5) for batch launches. Mitigation: remember last repo/tool as defaults; but novel-prompt launches stay a few clicks.
• No fleet-bottleneck spatiality — you can’t see a pileup of waiting agents as a column the way V3 does; you infer it from the badge count + sort.

21. Implementation Complexity

Lowest of the five (baseline). Rough estimate: low.

Why it’s the floor:

• The board is a standard responsive CSS grid of card components fed by one WebSocket state stream — no split-pane synchronization (V1), no drag/column-reflow choreography or status-driven card motion (V3), no command-palette/back-stack machinery (V4), and no bespoke feed-prioritization + swipe-gesture layer (V5).
• Navigation is plain routing (/, /agents/:id) + a modal and an interstitial — no novel interaction primitives.
• The two genuinely non-trivial pieces — the folded tool-adaptive detail (xterm.js over WebSocket for CLI / structured stream for API-native) and the live stdout previews — are shared across all five variations (every sibling must serve the deep-work layer and show live status), so they are not net-new cost relative to the set. Within the set V2 adds the least on top of that shared baseline.
• Reuses the shared tech stack + design system wholesale; owns only its grid layout, card component, and modal.

Largest single risk to the estimate is external, not structural: stdout-parsing reliability and terminal latency (both shared open questions), not V2’s own UI.

22. Prototype Scope

For the serial build → /uat --variant-evaluation comparison, prototype:

• S3 board with a mosaic of 6–8 live-ish cards spanning all states (running w/ streaming preview, waiting/pulsing, error/red, idle, completed-with-Review-diffs, starting) and the correct sort order; plus the empty state; plus the connection-lost banner.
• S4 modal end-to-end: repo dropdown, tool dropdown, prompt textarea, optional-branch toggle, validation-gated Start, the launching spinner, and a launch that drops a new starting → running card into the grid. Include the tool-unavailable error path.
• Folded detail route for both renderings: at least one CLI agent (xterm.js terminal with a stubbed live stream + inline approval overlay + prompt-injection footer) and one API-native agent (structured activity stream + inline approval). Include Back to Board.
• Responsive proof: the same prototype at all three breakpoints (1-col phone, 2-col tablet, 3-col desktop), including the mobile sheet modal and the mobile read-mostly terminal.
• Approval round-trip: click a waiting card → approve in detail → back → card now running.

Out of prototype scope (linked, not built here): full S9 diff review, S8 recap timeline beyond a stub, S10 settings, real push delivery, real tunnel/auth, and Mode C/IDE (excluded).

23. Readiness Signal for /ui-interview

This spec is ready to hand to /ui-interview [v2-card-mosaic] once V2 is selected or built. It fixes, for the visual-mockup stage:

• the board representation (responsive card grid), connection (full-page detail route), launch (modal), and device posture (co-equal responsive) — all four axes at the flow-map baseline;
• the screen inventory in scope (S3 board, S4 modal, folded S5/S6 detail) with regions, proportions, and three-breakpoint behavior;
• the component set, button/link behavior, hierarchy/density, and visual tone;
• the folded tool-adaptive detail decision (no Mode A/B toggle) and the out-of-scope calls (IDE/Mode C, multi-user sharing/permissions = N/A).

Open items the UI interview should resolve (not blockers, just the live questions): exact card dimensions / preview line-count, the precise side-rail width and collapse behavior in detail, the light-filtering affordance (status/repo chips) if any, and mobile terminal ergonomics copy (“open on desktop” handoff). Bounding open questions (terminal latency, stdout-parsing reliability) are flagged as risks, not resolved here, and carry forward as evaluation criteria.

1. Name & Thesis

Kanban Pipeline. The fleet is a status pipeline, not a list of things. Each agent is a card that lives in a lifecycle column — Queued → Running → Waiting-Approval → Error → Done — and moves between columns as its status changes. The conductor’s primary job here is triage, and triage is made spatial: a tall Waiting-Approval or Error column is an instantly visible bottleneck, readable in under a second from across the room or a glance at a phone. You don’t read rows and parse status badges; you read the shape of the board. Drill-in is a side drawer that slides over the board so the pipeline stays partially visible behind it — orchestration context is never fully lost when you go deep on one agent.

The wager: for a conductor running 5–12 concurrent agents, the most valuable on-screen signal is “where is the queue backing up?” and a status-keyed board answers that question with column height before the user reads a single word.

2. Parent User Flow & Branch Relationship

This variation is one of five sibling treatments of the monitoring-start branch. It covers:

• Happy Path 3–6: S3 Agent Board (the column board) → S4 Start Agent (inline add-card in the Queued column) → S3 new card appears in Queued, then animates into Running → S5/S6 Interact (the folded drawer).
• Path C “Parallel Sprint”: the columns ARE the parallel-sprint view. Launching agents #2 and #3 adds cards to Queued; as they spin up they flow into Running; round-robin approvals are literally “work the Waiting-Approval column top to bottom.”

Adjacent branches it touches but does not own: approval (S7) — here surfaced as the Waiting-Approval column + drawer-inline approval, not the full approval-routing experience; recovery (Path D) — surfaced as the Error column; device-handoff (Paths E/F) — surfaced as the persistent QR / “Open on Mobile” header control. Those branches get their own dedicated variation work; this spec only renders their entry points as columns/affordances on the monitoring-start surface.

Flow-map amendment carried (per brief): S5 + S6 are merged into one folded, tool-adaptive detail surface (the drawer). This contradicts the approved flow-map’s separate-screens + Mode A/B framing; the brief authorizes carrying the merged model in variations as a proposed amendment. The approved doc is not edited here.

3. Target User Fit

Best fit: the triage-first conductor — the user whose dominant loop is “scan the fleet, find what’s blocked, clear it, repeat.” This person runs 5–12 agents and experiences the board mostly as a queue-management problem: their pain is not “I can’t find agent X” but “which of my twelve agents need me right now and in what order?” The status-keyed board is purpose-built for that: it sorts the entire fleet into “needs-you” columns (Waiting-Approval, Error) vs. “leave-it-alone” columns (Running, Done) structurally, before any per-card reading.

Also fits: users with a project-management / kanban mental model (Trello, Linear board view, GitHub Projects) who already think in columns-as-status and will find the board immediately legible.

Poor fit: the deep-work-dominant user who spends most of their time inside ONE agent’s terminal for long stretches — the drawer is a good drill-in but the board’s motion behind it (cards moving columns) is a low-grade distraction for someone who wants the fleet to disappear. That user is better served by V4 Command-First (focus mode) or V1 Operator Console (persistent split-pane). Also poor for the pure-launch-velocity user who just wants to fire agents fast — the add-card is column-scoped and slightly slower than a global ⌘K (V1/V4) or a one-tap recipe (V5).

4. Onboarding / Activation Model (Empty Columns State)

This variation does not own first-time setup (that’s the onboarding branch, Path A → S2/S10). It owns the empty board a fresh-but-provisioned workspace lands on.

Empty-columns state. On a provisioned workspace with zero agents, the board renders all five column headers in their resting positions (Queued, Running, Waiting-Approval, Error, Done), each empty but structurally present — this teaches the lifecycle model at a glance: “agents are born in Queued and flow rightward.” The columns are not hidden; their visible emptiness is the onboarding.

• The Queued column shows a prominent, pulsing “+ Start your first agent” add-card affordance at its head — this is the single primary CTA and it sits exactly where the user’s first agent will live.
• The other four columns each show a one-line muted ghost caption explaining their role: Running — “active agents appear here,” Waiting-Approval — “agents needing your OK,” Error — “agents that hit a problem,” Done — “completed work, ready to review.” These captions vanish the moment a column receives its first card.
• A dismissible “How the board works” strip under the header gives a one-sentence orientation: “Agents flow left-to-right as their status changes. Watch the Waiting-Approval and Error columns — that’s your queue.”

Activation moment for this surface: the user clicks the Queued add-card, fills the inline launch form (§13/S4), and watches the new card appear in Queued and animate one column right into Running. That single observed transition — card moves on its own as status changes — is the “aha” specific to this variation: the board is alive and self-sorting. Time-to-first-agent target: under 30 seconds from empty board.

5. Typical Workflow Sequence

1. Land on the board (S3). Returning user opens the PWA → routed to the column board. Instant read: scan column heights. Tall Waiting-Approval or Error = work to do; everything in Running/Done = relax.
2. Triage by column, not by card. Eye goes first to Error (leftmost of the “needs-you” pair, highest priority), then Waiting-Approval. Within a column, cards are ordered oldest-blocked-first (stable; see §6/§20).
3. Clear a blocker. Click the top card in Waiting-Approval → drawer slides in over the board (board dims but stays visible behind). Drawer shows the folded detail; the inline approval card is right there. Approve → card animates out of Waiting-Approval and back into Running (or into Done if the approval was the final step).
4. Work the column down. Approve / unblock the next card. Because ordering is stable, “the next one” stays put — you’re not chasing a reflowing list.
5. Launch new work (S4). Click “+” at the head of the Queued column → compact inline launch form expands in place (repo / tool / prompt). Submit → card lands in Queued → auto-advances to Running on spawn. Repeat for parallel sprint (#2, #3).
6. Go deep on one agent (folded S5/S6). Click any Running card → drawer opens to the tool-adaptive detail: terminal-primary (xterm.js) for CLI tools, structured stream for API-native tools. The opened card is pinned in its column (§20) so it does not slide away under you while you work.
7. Escalate / intervene. From the drawer, inject a prompt, stop/restart, or — for CLI tools — drop straight into the live terminal that the drawer already hosts. For an errored agent, the drawer opens with the error output + Retry/Restart/Terminal controls.
8. Resolve & dismiss. Close the drawer (Esc, backdrop click, or X) → board returns to full view; any status changes that occurred while the drawer was open are reflected (the closed card may now be in a different column).
9. Review completed work. Cards in Done carry a “Review diffs” affordance → routes to S9 (diff review, owned by the diff-review branch). Done is the staging area for shipping.
10. Repeat. The loop is scan-shape → triage-column → clear → relaunch.

6. Progression Model — and Explicit Contrast vs. the 4 Siblings

How the user advances in V3: progression is the card’s literal motion through columns. “Advancing” a task = moving its card rightward (Queued → Running → Done) or unblocking it (Waiting-Approval/Error → Running). The user’s mental model of “where am I” is answered by which column the card is in. The system moves cards automatically on status change (server-canonical via WebSocket); the user moves them indirectly by acting on blockers. There is no manual drag in the default model — columns are status-derived, not user-assigned buckets (dragging a card to “Done” would lie about agent state). The progression metaphor is a pipeline you unblock, not a board you arrange.

Explicit contrast with siblings:

• vs. V1 Operator Console (dense table + persistent split-pane): V1 keeps a single flat sortable table always in view and shows detail in a fixed right pane — progression is reading a re-sorted row position. V3 replaces the sort with spatial columns and replaces the always-on split-pane with an on-demand drawer. V1 never hides the full fleet; V3 deliberately dims it behind the drawer. V1 = density-max NOC; V3 = shape-first triage.
• vs. V2 Card Mosaic (responsive grid + full-page route): V2’s progression is a status badge changing on a card that stays put in a grid; drill-in is a full-page route that drops board context entirely. V3’s progression is the card moving between columns, and the drawer keeps the board visible. V2 answers “what is each agent doing”; V3 answers “where is the fleet backing up.” (V2 is the control/baseline; V3 is its triage-optimized counterpoint.)
• vs. V4 Command-First (quiet list + palette + focus mode): V4 makes progression invisible/quiet and drives everything through ⌘K; detail is a full focus mode with a back-stack. V3 is the opposite philosophy — progression is maximally visible and spatial, discoverable without any command knowledge. V4 optimizes for the keyboard-native who wants the board to recede; V3 optimizes for the at-a-glance triager who wants the board to shout.
• vs. V5 Glanceable Stream (mobile-first prioritized feed): V5 collapses the fleet into ONE prioritized vertical feed (approvals/errors pinned top) — progression is feed reorder. V3 keeps work separated into status columns rather than merged into a single ranked stream. V5’s single column is phone-native; V3’s multi-column is desktop-native and reflows to stacked sections on mobile (§17). V5 hides the lifecycle; V3 makes the lifecycle the whole UI.

One-line summary of the axis V3 owns: progression is spatial and automatic (card motion across status columns), drill-in preserves the board (drawer), launch is column-anchored (+ in Queued).

7. Sharing & Collaboration Model

N/A — single-user personal workstation. This is a solo dogfood environment; there is no second user to share a board, column, card, or drawer with. No shared boards, no card assignment to teammates, no comments, no presence/cursors, no collaborative columns. (Kanban tools often imply assignment-to-people; that semantic is explicitly absent here — columns are keyed to agent lifecycle status, never to a person or owner.) Cross-device access by the same user is covered by the device-handoff branch (server-canonical state + QR), not by any sharing mechanism.

8. Permissions Model

N/A — single-user personal workstation. No roles, no per-column or per-card permissions, no multi-tenant access control, no viewer/editor distinction. The only identity/authorization in the system is the user’s own GitHub OAuth (identity + repo scopes so agents can pull/push/PR) and the user’s own model keys/subscriptions (BYO, never touched by the board) — both owned by the onboarding/settings branches, not surfaced as a permissions layer on this board. Every agent and every column belongs to the one user.

9. Return-Use & Notification Model

The two “needs-you” columns are the persistent triage queue — this is V3’s core return-use strength.

• The board is the inbox. On every return, the user reads column shape first. A non-empty Error column or a non-empty Waiting-Approval column is the standing “you have work” signal — no separate inbox/badge needed for the primary read (though a header count badge mirrors it for the collapsed/mobile view). The queue is the board; there is no second place to check.
• Column-as-queue ordering. Within Waiting-Approval and Error, cards are ordered oldest-blocked-first (FIFO by block-time), so “work the column top-down” is the natural and stable triage order. This ordering is frozen — see §20; new blocked cards append to the bottom so the card you’re about to act on never jumps.
• Push notifications (Web Push via service worker). When an agent enters Waiting-Approval or Error while the user is away, a push is sent to all subscribed devices (“Agent needs approval” / “Agent hit an error”). Tapping the push deep-links the PWA directly to that card’s drawer open over the board — the user lands exactly on the blocker, with the board’s triage context one Esc away. (Honors the approval/device-handoff branch contracts; falls back to S3 board if the deep link can’t resolve.)
• Done as a soft queue. The Done column accumulates completed agents awaiting review; its height is the “ready to ship” backlog signal, with a per-card “Review diffs” handoff to S9.
• Return-after-absence. If the time gap exceeds the recap threshold (D7), an Async Recap (S8) summarizing what changed while away is offered before the board — but the board itself, with its self-sorted columns, is the durable always-correct state once dismissed.

10. Failure Recovery Behavior

Mapped to the flow-map Failure & Recovery Paths table and Path D (recovery). The Error column is the spatial home of failure on this surface.

Error column’s distinct role: it is the only column that demands action AND implies something went wrong (vs. Waiting-Approval, where the agent is healthy and just wants a decision). Keeping Error as a separate, leftmost-priority column means a single glance distinguishes “broken” from “blocked,” which the flat-table (V1) and single-feed (V5) treatments blur together under a generic “needs attention” sort.

11. Page & Flow Changes vs. the Flow-Map Baseline

No screens are added or removed; S7/S8/S9/S10 are reached via the same handoffs (now from columns/cards/drawer instead of grid cards/modal). The flow-map document itself is not edited (amendment proposed, per brief).

12. Navigation Model

• Primary nav = the board itself. There is no left sidebar of views; the columns are the navigation. Horizontal eye-scan across columns is the “menu.”
• Header (persistent): app name; a compact mirror of the two queue columns as count badges (⚠ 2 errors · ⏳ 3 waiting) for the at-a-glance read when scrolled or collapsed; settings gear (→ S10); QR / “Open on Mobile” control (device-handoff). The header never scrolls away.
• Drill-in: click any card → side drawer (right-anchored on desktop/tablet, bottom-sheet on mobile — §17). Drawer is a transient overlay, not a route push on desktop; on mobile it pushes a history entry so the back gesture closes it.
• Drawer-internal nav: the folded detail has lightweight chrome tabs/segments within the drawer (e.g., “Detail” structured summary always present; “Terminal” live view for CLI tools) — these are not the dropped Mode A/B user toggle; they are progressive disclosure of the same tool-adaptive surface (terminal is the native interface for CLI tools and is the default-focused region for them).
• Escape paths: Esc / backdrop-click / drawer X → back to full board. Browser back on mobile closes the drawer; on desktop browser back leaves the board surface.
• Cross-branch jumps: Done card “Review diffs” → S9; drawer “Settings”/credential links → S10; header gear → S10; recap (S8) interstitial on threshold returns.
• Deep-link targets (PWA): push/QR can open directly to board, a specific card’s drawer, or the approval column scrolled into view.

13. Screen-by-Screen Layout (Regions & Proportions)

S3 — Column Board (the home surface)

• Header band (~56px desktop, ~52px mobile, fixed): left = app name; center-left = queue-mirror count badges; right = QR/Open-on-Mobile + settings gear. Below it, an optional dismissible 1-line orientation strip (empty state only).
• Column rail (fills remaining viewport height): a horizontal row of 5 columns on desktop. Default proportional widths are equal-ish but priority-weighted — the two “needs-you” columns (Error, Waiting-Approval) get slightly more width (~22% each) than Queued/Running/Done (~18% each) so blocked cards have room for richer reason text. Columns scroll internally/vertically (a backed-up column scrolls within its own track; the board does not grow taller). On desktop the 5 columns fit without horizontal scroll at ≥1024px; a narrow desktop may horizontal-scroll the rail.
• Column header (per column, sticky to column top): status label + live count + a thin color accent bar (Error red, Waiting amber, Running green, Queued neutral-blue, Done muted-green). The Queued column header also hosts the “+” add-card button.
• Cards (within columns): compact, vertically stacked, fixed order (oldest-blocked-first / spawn-order). Card content (~88–110px tall): agent name, tool chip, repo, status-relevant line (elapsed time for Running; blocked-for duration for Waiting/Error; error summary for Error; one-line stdout for Running; completion summary for Done). A subtle live-stdout shimmer on Running cards.
• Column ordering (left→right): Error · Waiting-Approval · Running · Queued · Done. (Highest-attention leftmost, honoring error > waiting > running priority; Queued and Done — the low-attention bookends — sit toward the right. This is configurable but ships with this default.)

S4 — Inline Add-Card (launch)

• Triggered by “+” in the Queued column header. The card slot at the top of Queued expands into a compact inline form (no modal, no backdrop; board fully visible behind it):
  • Repo picker (dropdown, auto-populated from GitHub OAuth) — skeleton-loads if repos still fetching.
  • Tool selector (dropdown; flags unavailable tools with an “Install” link → S10).
  • Prompt textarea (2–3 lines, expandable).
  • Optional branch field (collapsed under “more”).
  • Start (primary) / Cancel (secondary). Start disabled until repo+tool+prompt set (mirrors S4 “Ready” state).
• On Start: button shows spinner (“Starting agent…”), form locks; on success the form collapses and a new card materializes in Queued, then animates one column over into Running as the process spawns. On failure: inline error + Retry, form re-enabled, no orphan card.
• Form proportions: occupies ~the top third of the Queued column width; remaining queued cards push down beneath it.

Drawer — Folded S5/S6 Detail (tool-adaptive)

• Trigger: click any card. Drawer slides in from the right (desktop/tablet) or up from the bottom (mobile). Width: ~44% of viewport on desktop (board occupies the left ~56%, dimmed but live), ~60% on tablet, full-width bottom sheet on mobile. A scrim dims the board but does not hide it; board remains scroll-locked-but-visible.
• Drawer regions (top→bottom):
  • Header: agent name, tool chip, repo, live status pill (mirrors which column it’s in), elapsed/blocked duration, drawer X + QR (deep-link to this agent on mobile).
  • Primary detail region (tool-adaptive, folded):
    • CLI tools (Claude Code CLI, Codex CLI, Cursor worker, Aider, Continue, Cline, Copilot CLI, Augment): the xterm.js terminal IS the primary region (live, over WebSocket), filling most of the drawer height. A thin structured strip wraps it (parsed step/file-change summary) above the terminal. This honors “the terminal is the native interface” — no separate Mode B.
    • API-native (Claude Agent SDK): the structured stream is the primary region — parsed steps, progress, file-change list; no terminal (none exists server-side).
  • State-conditional inline panels: when the card is in Waiting-Approval, an inline approval card (diff preview, Approve/Reject/Modify/Defer) sits at the top of the detail region. When in Error, an error/stack panel with Retry / Restart / Open-Terminal sits there.
  • Footer (action bar): prompt-injection input, Stop / Restart, and (for CLI) terminal focus. Persistent across states except when disabled by reconnect.
• Pinning: the moment the drawer opens for a card, that card is pinned in place in its column (see §20) so background status churn cannot slide it away while the user works.

14. Key Components & Controls

• Status Column — titled, color-accented, internally-scrolling vertical track; live count in header; the unit of triage.
• Agent Card — compact, status-adaptive content; the unit that moves. Carries name, tool chip, repo, status line, live-stdout shimmer (Running), blocked-duration (Waiting/Error), completion summary (Done).
• “+” Add-Card — column-header affordance (Queued) that expands the inline launch form.
• Inline Launch Form (S4) — repo/tool/prompt/branch, Start/Cancel, in-place validation & error.
• Side Drawer — overlay detail host; right-anchored (desktop/tablet) / bottom-sheet (mobile); board stays behind.
• Tool-Adaptive Detail Region — xterm.js terminal-primary (CLI) or structured-stream-primary (API), folded; thin chrome wraps it.
• Inline Approval Card — appears in drawer when Waiting-Approval (diff preview, Approve/Reject/Modify/Defer).
• Error Panel — drawer error/stack view + Retry/Restart/Open-Terminal.
• Queue-Mirror Header Badges — ⚠ errors · ⏳ waiting counts; persistent at-a-glance read.
• Reconnect Banner — top-of-board, freezes card motion, disables launch/actions.
• QR / Open-on-Mobile — header + drawer-scoped deep-link handoff.
• Empty-Column Ghost Captions — onboarding-only column descriptions.

15. Button & Link Behavior

• “+” (Queued header): expands the inline launch form at the top of Queued; toggles closed on re-click/Cancel. Disabled (with reconnect tooltip) while WebSocket is down.
• Start (launch form): disabled until repo+tool+prompt valid; on click → spinner + lock → success collapses form & spawns card (Queued→Running animation); failure → inline error + Retry. Tool-unavailable → “Install tool” link routes to S10.
• Card (whole card is the click target): opens the drawer to the folded detail; pins the card. Keyboard: cards are focusable; Enter opens drawer; arrow keys move focus within/across columns.
• Drawer X / Esc / backdrop: closes drawer, unpins card, returns to full board (board reflects any status changes that occurred while open).
• Approve / Reject / Modify / Defer (drawer inline approval): Approve → agent resumes, card animates Waiting-Approval→Running (or →Done); Reject → opens reason textarea then sends feedback; Modify → prompt-injection; Defer → leaves card in Waiting-Approval (drops to bottom of FIFO so you can come back). Sub-second delivery to agent control socket.
• Retry / Restart (drawer error panel): Retry re-runs same prompt; Restart re-spawns; success animates card Error→Running; Open-Terminal focuses the drawer’s xterm.js (CLI tools).
• Stop (drawer footer): halts the agent; card moves to Done (stopped) or back to Queued depending on stop semantics.
• “Review diffs” (Done card): routes to S9 diff review (diff-review branch).
• Settings gear / credential links: route to S10.
• QR / Open-on-Mobile: opens QR overlay encoding a one-time pre-authed deep link to current view (board / this card / approval column).
• Push-notification tap: deep-links to the relevant card’s drawer over the board (fallback: board).
• Recap “Got it” (S8): dismisses interstitial → board.

16. Spatial Density, Sizing, Hierarchy

• Density: medium-high but vertically dense, horizontally distributed. Cards are compact (~88–110px) so a column can show 6–10 cards before internal scroll — important because a backed-up triage column is the key signal and you want several cards visible at once. Across the 5 columns the board comfortably holds the 5–12 agent target without the board itself scrolling.
• Hierarchy (descending): (1) column height/shape — the loudest signal, read pre-attentively; (2) column color accent — Error red / Waiting amber draw the eye; (3) card status line (blocked-duration, error summary); (4) per-card metadata (tool, repo, elapsed). The design deliberately makes aggregate shape outrank individual card detail — the inverse of V1’s row-detail-first density.
• Sizing logic: “needs-you” columns slightly wider for reason text; “leave-it-alone” columns tighter. Touch targets ≥44px on mobile (whole card tappable). Drawer sized to keep ~56% of the board visible on desktop so orchestration context persists during deep work.
• Whitespace: generous between columns (clear separation = clear status boundaries); tight within a column (compact stack = readable height). This contrast is load-bearing: it’s what makes column shape legible at a glance.

17. Responsive Behavior (3 Breakpoints) — Column Reflow Strategy

The defining responsive move: horizontal columns reflow to vertically stacked status sections.

• Desktop (>1024px): all 5 columns side-by-side in a horizontal rail; columns scroll internally. Drawer is right-anchored, ~44% width, board stays visible (~56%) behind a scrim. This is the variation’s home posture (desktop-leaning, per the axis).
• Tablet (≤1024px): columns condense — either 5 narrower columns if they fit, or a 2.5-column horizontally-scrollable rail (Error + Waiting-Approval pinned visible by default since they’re priority; Running/Queued/Done scroll into view). Cards slightly more compact. Drawer right-anchored at ~60% width.
• Mobile (≤640px): columns reflow to vertically stacked, collapsible status sections — one full-width section per status, stacked Error → Waiting-Approval → Running → Queued → Done (priority order top-down). Each section header shows its status + count and is collapsible; Error and Waiting-Approval expand by default, Running/Queued/Done collapse by default to keep the triage queue above the fold. A sticky header queue-mirror badge (⚠2 ⏳3) gives the instant read without scrolling. The “+” add-card lives in the (possibly collapsed) Queued section header and also as a floating action button bottom-right for one-tap launch. Drawer becomes a full-width bottom sheet (board no longer “behind,” but back-gesture/Esc returns to it). Terminal in the drawer is read-mostly on mobile with an “open on desktop” QR handoff (honors the latency bound — heavy interactive terminal use is steered to desktop).

Reflow rationale: the status-section stack on mobile preserves the exact triage semantics (priority order, count-per-status, expand-the-blockers) that the desktop columns provide — the mental model survives the reflow; only the axis (horizontal → vertical) changes.

18. Visual Tone

Dark, calm-operational, shape-led. Honors the house dark palette (--bg:#1a1a2e; --card:#16213e; --border:#2a2a4a; --accent:#4dabf7; --text:#e0e0e0; --muted:#8b8fa3). Status color is the one place chroma is spent and it’s spent meaningfully:

• Error — red accent (~#e03131), highest-contrast.
• Waiting-Approval — amber (~#f08c00).
• Running — green (~#37b24d), but quiet (a thin accent + subtle stdout shimmer, not a glowing card — Running should feel calm, “leave it alone”).
• Queued — neutral blue (the house --accent).
• Done — muted green-gray (recedes; work is finished).

Motion is purposeful and restrained — card transitions between columns are short, eased, and rate-limited (§20) so the board reads as a settling pipeline, not a churning one. Typography compact and monospace-leaning in the terminal drawer; sans elsewhere. Overall feel: a quiet ops board where the only loud thing is a column that needs you.

19. Strengths

• Fastest triage read in the set. Bottlenecks are spatial — a tall Error/Waiting column is legible pre-attentively, before reading any card. Best-in-class answer to “where is the fleet backing up?”
• Self-sorting fleet. The board organizes itself by status with zero user effort; the known-good error>waiting>running priority becomes layout.
• Board-preserving drill-in. The drawer keeps orchestration context visible during deep work — you don’t lose the fleet to go fix one agent (unlike V2’s full-page route).
• Distinguishes “broken” from “blocked.” Separate Error and Waiting-Approval columns make a distinction that flat-sort (V1) and single-feed (V5) treatments blur.
• Strong return-use. The two queue columns are the inbox; no separate triage surface to maintain. Push deep-links land on the exact card.
• Legible mental model. Anyone with kanban/Linear/Projects exposure reads it instantly; the empty board teaches the lifecycle for free.
• Parallel-sprint native. Path C (launch #2/#3, round-robin approvals) maps perfectly onto “add to Queued, work the Waiting column down.”

20. Risks & Failure Modes (with Mitigations)

The brief flags V3’s inherent risks explicitly. Addressing each:

• Card motion / board instability. Cards moving columns on status change creates churn that can be distracting and can cause the click-target you were aiming at to jump.
  • Mitigation 1 — Pin the open card. The instant a card’s drawer opens, that card is pinned in place; it will not move columns underneath the user, and its visual position is locked until the drawer closes (its true status is still tracked; the move is deferred and applied on close, with a subtle “moved to Running” toast).
  • Mitigation 2 — Stable within-column ordering. Cards within a column are ordered by a stable key (block-time / spawn-time, oldest-first, append-on-arrival). New cards enter at the bottom; existing cards never reshuffle. “The next one to act on” stays put.
  • Mitigation 3 — Rate-limited, eased, batched transitions. Column moves animate with a short eased transition and are coalesced (rapid flapping status — e.g., transient retry — resolves to a settled state before animating; cards don’t bounce between columns on every micro-event). Auto-restart retry sub-states animate in place in Running, not as a trip to Error and back.
  • Mitigation 4 — Motion respects reduced-motion. prefers-reduced-motion swaps slide animation for an instant cross-fade reposition.
• Weak deep-work continuity. A user living inside one agent’s terminal feels the board churning behind the drawer.
  • Mitigation: the pinned card + the board scrim dimming the background reduce perceived motion; the drawer can be maximized (toggle to ~80% width / full-screen) for sustained deep sessions, effectively hiding the churning board for users who want it. The tool-adaptive terminal-primary region means CLI deep work is first-class inside the drawer, not a degraded secondary view. (Users whose dominant loop is single-agent deep work are explicitly steered to V4/V1 — §3.)
• Slower pure launch. Column-anchored “+” is one step more than a global ⌘K or one-tap recipe.
  • Mitigation: keep the add-card always visible at the head of Queued (no menu-hunt); add a keyboard shortcut (n) that opens it from anywhere on the board; on mobile a floating “+” FAB gives one-tap access. Accept that raw launch velocity is not this variation’s optimization target — triage is — and let V1/V4/V5 own launch-speed in the comparison.
• Horizontal-scroll trap on narrow desktop / tablet. 5 columns can overflow.
  • Mitigation: priority columns (Error, Waiting) pinned visible; the rest horizontally scroll; tablet may drop to a 2.5-column rail (§17). Mobile abandons columns entirely for stacked sections.
• Empty/idle columns waste space. With few agents, several columns sit empty.
  • Mitigation: empty columns collapse to a thin labeled rail (still present for model-teaching, but width-minimized) once past the onboarding empty state, reclaiming width for active columns.
• Stdout-parsing reliability bound. Per-card status lines and the structured strip depend on Multica-style parsing (open question).
  • Mitigation: column placement is driven by coarse lifecycle state (process running / blocked / errored / done — robust signals), NOT by fine stdout parsing; parsed stdout only enriches the card’s secondary line. If parsing is unreliable for a tool, the card still sits in the correct column; only the one-line preview degrades to raw last-stdout-line. Triage never depends on parse quality.
• Terminal-latency bound. Drawer terminal is the live interface for CLI tools.
  • Mitigation: desktop drawer leans on live xterm.js; mobile drawer is read-mostly with “open on desktop” QR handoff (§17), keeping heavy interactive terminal use where latency is acceptable.

21. Implementation Complexity

Estimate: medium-high — among the higher of the five (above V2 baseline, V4, V5; roughly peer to or slightly above V1).

Drivers:

• Column engine with stable + pinned ordering. The hard part is not drawing columns; it’s the motion-control logic: stable within-column sort keys, pinning the open card and deferring its move, coalescing/rate-limiting transitions to avoid flapping, reduced-motion fallbacks. This is real state-machine + animation-orchestration work that the grid (V2) and list (V4) treatments don’t need.
• Reflow across 3 breakpoints with semantic preservation. Horizontal columns → 2.5-col rail → stacked collapsible sections, keeping priority/count/expand-blockers semantics — more responsive surface area than a grid that just changes column count.
• Drawer overlay with live board behind. Right-drawer + scrim + keep-board-rendered-and-live (WebSocket keeps updating the dimmed board) + maximize toggle + mobile bottom-sheet variant.
• Folded tool-adaptive detail (shared cost). xterm.js-over-WebSocket terminal-primary for CLI + structured-stream for API, inside the drawer — this cost is shared with all siblings, but here it’s hosted in an overlay that must coexist with a live board.

Lower-cost relative to V1: no dense virtualized table; relative to V5: less novel gesture/swipe surface. The net premium over the V2 control is squarely in the column motion-control + reflow machinery.

22. Prototype Scope

For the build-grade prototype (feeds /uat --variant-evaluation and /ui-interview):

• In scope:
  • S3 column board, 5 columns, with mock live data of ~8–10 agents distributed across statuses (including a deliberately tall Waiting-Approval and a populated Error column to demonstrate the triage read).
  • Card-motion demo: scripted status transitions so cards visibly animate between columns; demonstrate pinning (open a drawer, trigger a background status change, show the card holds) and stable ordering.
  • S4 inline add-card in Queued: full form, validation, Start → card materializes in Queued → animates to Running.
  • Drawer drill-in for both tool patterns: one CLI agent (xterm.js terminal-primary, can be a recorded/replayed stream for the prototype) and one API-native agent (structured stream). Include the inline-approval state and the error-panel state.
  • Responsive demo at all 3 breakpoints, showing the horizontal→stacked-sections reflow and mobile bottom-sheet drawer + Error/Waiting expanded-by-default.
  • Reconnect banner (frozen columns, disabled launch).
• Out of scope (stubbed/linked): real WebSocket backend & real tool processes (mock/replay); S7 full approval-routing, S8 recap, S9 diff-review, S10 settings (link out / stub — owned by other branches); real GitHub OAuth & model keys; push-notification delivery (show the deep-link landing, not the push pipeline); code-server / IDE (out of scope per bounding open question — not argued in for this variation).
• Fidelity: dark house palette, real layout/proportions/motion; data mocked.

23. Readiness Signal for /ui-interview

This spec is ready to feed /ui-interview [v3-kanban-pipeline]. It locks the load-bearing decisions: status-column board representation, side-drawer drill-in with the board preserved, inline “+” add-card launch, desktop-columns→stacked-sections reflow, and the folded tool-adaptive detail (no Mode A/B toggle). It maps all four monitoring-start screens (S3/S4/S5/S6) and their state matrices, addresses the inherent card-motion risk with concrete mitigations (pin-open-card, stable ordering, rate-limited/coalesced transitions), and ships N/A statements for sharing/collaboration/permissions per single-user scope.

Open items deliberately deferred to /ui-interview (visual decisions, not flow decisions): exact column proportions and the empty-column collapse threshold; final status chroma values within the dark palette; drawer width ratios and the maximize-toggle breakpoint; card content density (which secondary line to show per status); the precise tablet behavior (5 narrow columns vs. 2.5-col rail) — to be settled empirically. None of these block the visual mockup; they are its agenda.

Bounding open questions carried forward (not resolved here): terminal latency (drawer terminal interactivity vs. mobile read-mostly handoff), stdout-parsing reliability (mitigated by coarse-lifecycle-driven column placement), and code-server/IDE (held out of scope — not argued in).

1. Name & Thesis

Command-First. The fleet is a quiet, low-chrome list; the verb is a command palette (⌘K). Every action — launch, filter, jump, approve, escalate to terminal — is a command, not a hunted-for button. Opening an agent enters a full-attention focus mode with the board held as a back-stack (Esc / breadcrumb returns). The mental model is a terminal multiplexer or an editor command palette, ported to the web: a keyboard-native developer who resents pointing-and-clicking through UI gets a surface where typing is the navigation. Chrome stays out of the way until summoned; the orchestration layer (S3/S4) and the deep-work layer (S5/S6) are stitched together by one consistent typed grammar rather than by spatial layout.

2. Parent User Flow & Branch Relationship

This variation is one of five sibling expressions of the monitoring-start branch. It serves the two-layer surface the brief mandates:

• Orchestration layer (S3 board + S4 launch): the quiet list is the scan surface; the palette is the launch + triage surface. Maps to Happy Path step 3 (board), step 4 (start agent), step 5 (new card appears), and Path C steps 1–5 (parallel sprint: launch #2, #3, monitor all, round-robin approvals).
• Deep-work layer (S5 detail + S6 terminal, folded): focus mode is the single detail screen. Maps to Happy Path step 6 (interact) and the failure/recovery touchpoints (Path D) that flow through detail.

Per the brief’s confirmed reframe, detail is folded + tool-adaptive: focus mode renders terminal-primary (xterm.js over WebSocket) for CLI tools and structured for API-native tools. There is no Mode A/B user toggle — rendering is determined by the agent’s tool integration pattern. The command-first ethos pairs naturally with CLI terminals (a keyboard user living in a terminal is the design’s home turf), and we lean into that, but the rendering choice remains tool-determined, not user-selected.

Upstream screens S7 (approval), S8 (recap), S9 (diff) are adjacent and reachable but owned by sibling branches; this spec treats them as palette/focus-mode destinations only where monitoring-start touches them (inline approval, error triage).

3. Target User Fit

The keyboard-native Agent Conductor: a solo developer running 5–12 concurrent agents across 1–3 repos who already lives in vim/tmux/VS Code-command-palette/Raycast and instinctively reaches for ⌘K before reaching for the mouse. This user:

• Resents hunting UI; wants muscle-memory speed over visual scanning.
• Is comfortable typing structured commands and remembering a small grammar.
• Spends most desktop time inside one agent (deep work), dipping back to the fleet to fan out or triage.
• Treats the phone as a glance-and-approve device, not a primary driver.

Poor fit: a user who wants to see the whole fleet at a glance with rich live previews (better served by V2 Card Mosaic or V5 Glanceable Stream), or who triages spatially by status column (V3 Kanban). Command-First trades glanceability for velocity.

4. Onboarding / Activation Model

The risk of a command-first UI is invisible capability. We confront it at activation:

• First board paint (empty state): centered, the board shows a single large, blinking command-prompt affordance: a faux input reading Press ⌘K to start your first agent with a visible ⌘K chip. It is also a real clickable button — clicking it opens the palette. Below it, 3–4 suggested starter commands are rendered as clickable chips: start agent, filter status:error, jump to <agent>, ? help. Clicking a chip pre-fills the palette so the user sees the grammar before typing it.
• First palette open: the palette opens in discovery mode — instead of a blank field, it lists grouped suggested actions (Launch / Navigate / Filter / Help) with their keyboard shortcuts shown inline. Typing narrows the list (fuzzy match). This means a brand-new user can drive the whole product by arrow-keys + Enter, never having memorized a single command.
• Persistent hint bar (always-visible): a thin bottom bar shows context-relevant shortcuts at all times (e.g. on the board: ⌘K Command · / Filter · ↵ Open · ? Help). It is the antidote to “where did the buttons go.” It updates per screen (board vs focus mode).
• ? Help overlay: a full command reference grouped by category, searchable, always one keystroke away.
• Activation = first agent launched via the palette. Success metric for onboarding: user reaches “running” agent without clicking a traditional button (or, if they clicked the empty-state chip, they saw the command echo into the palette and learned it).

After first launch, the empty state is replaced by the quiet list (§13).

5. Typical Workflow Sequence

1. Land on board (returning session) → quiet list of agents, sorted error > waiting > running > idle. Hint bar visible at bottom.
2. Scan the list — status dots + one-line status give a fast read of who needs attention.
3. ⌘K → start agent → palette walks a typed/guided launch: start agent on <repo> with "<prompt>" (tool inferred or appended using <tool>). Enter fires the launch.
4. New agent appears in the list with a starting dot, flips to running within seconds (server-canonical via WebSocket).
5. Fan out (Path C): ⌘K again → start agent on <repo-2>…, again → <repo-3>…. Each is a few keystrokes; no modal context-switch friction.
6. Triage: ⌘K → filter status:waiting (or just / to filter the list inline) → list collapses to agents needing approval.
7. Jump in: ⌘K → jump to <agent> (or arrow + Enter on the list) → focus mode opens; board pushed onto back-stack.
8. Deep work: focus mode renders terminal-primary (CLI tool) or structured (API tool). Type into the terminal / inject a prompt / approve inline.
9. Approve from focus mode: ⌘K → approve (acts on the focused agent) or click the inline approval card.
10. Return: Esc (or click breadcrumb) pops focus mode, restoring the exact board scroll/filter state from the back-stack.
11. Repeat triage → focus → return across the fleet. Round-robin approvals (Path C step 5) are ⌘K → approve next walking the waiting queue.

6. Progression Model — and Explicit Contrast vs. Siblings

How the user advances in V4: progression is verb-driven, not spatial. The user moves forward by issuing the next command, and moves deeper by jumping into focus mode (board → back-stack). The palette is the single throughline that unifies orchestration and deep-work: the same ⌘K surface starts an agent, filters the fleet, jumps to an agent, and acts on the focused agent. “Advancing” feels like a REPL — type, execute, observe, type again.

Explicit contrast with the other four siblings (per brief):

• vs. V1 Operator Console (persistent split-pane): V1 keeps the fleet always visible in a dense table beside the detail; you never lose the fleet. V4 hides the fleet behind focus mode (back-stack) for full single-agent attention, trading constant fleet-visibility for distraction-free depth. V1 progresses by clicking rows; V4 by typing commands.
• vs. V2 Card Mosaic (full-page route): V2 drills in via a route that drops board context; returning re-renders the board. V4’s back-stack preserves exact board state (scroll, filter) on return. V2 launches via modal; V4 via palette.
• vs. V3 Kanban Pipeline (status columns + side drawer): V3 makes status spatial — triage is scanning columns, and cards physically move as status changes. V4 makes status typed — triage is filter status:error; the list reorders quietly without spatial motion. V3 drills into a drawer over the board; V4 into a covering focus mode.
• vs. V5 Glanceable Stream (mobile-first feed): V5 is built phone-up with big tap targets, swipe actions, and recipe-based quick-start. V4 is built keyboard-desktop-first; on mobile it degrades to a bottom command bar (typed, not swiped). V5 optimizes for “approve from phone in 30s”; V4 optimizes for “fan out and deep-work from a keyboard.”

The shared progression invariant (per brief): all five serve both the orchestration and deep-work layers and use the folded tool-adaptive detail. V4’s distinctive claim is that the connection between layers is a typed command surface, not a spatial relationship.

7. Sharing & Collaboration Model

N/A — single-user personal workstation. Per the flow-map’s explicit non-goals and the brief’s single-user scope, there is no sharing, no shared boards, no co-presence, no comment/mention surface. The palette grammar deliberately contains no share/invite/assign verbs. (If multi-tenant ever arrives it is a separate product surface, out of scope here.)

8. Permissions Model

N/A — single-user personal workstation. There are no roles, no per-agent ACLs, no collaborator permissions. The only auth boundary is the single user’s GitHub OAuth session (identity + repo scopes), which is a session/connectivity concern owned upstream (S1), not a UX permission model on this surface. No permission UI appears in the board, palette, or focus mode.

9. Return-Use & Notification Model

The challenge: a quiet list must still make approvals and errors impossible to miss without becoming noisy. Mechanisms:

• Quiet-list priority: the list is always sorted error > waiting > running > idle. Anything needing attention floats to the top by construction. Error rows carry a red status dot; waiting rows an amber dot with a subtle pulse (the only motion in the otherwise-still list).
• Hint-bar attention counter: the always-visible hint bar shows a compact counter when items need action, e.g. 2 waiting · 1 error rendered as a tappable/keyboard-reachable token. Pressing it (or ⌘K → approve next) walks the queue.
• Palette as inbox: ⌘K opens with context-aware top suggestions — if approvals are pending, the palette surfaces approve next (2) and jump to <error-agent> as the first ranked suggestions. The palette doubles as a prioritized action inbox without a separate notification panel.
• Push notifications (PWA): approvals/errors fire Web Push to connected devices (per flow-map). Tapping a push deep-links straight into focus mode for that agent (board pre-loaded on the back-stack so Esc still works). Falls back to the board if the deep link can’t resolve.
• Returning after absence: if the time gap exceeds threshold (flow-map D7), the palette’s first suggestion becomes show recap (S8), and the hint bar shows the since-last-seen counter. Recap itself is owned by device-handoff, but V4 routes to it through the same palette grammar.
• No badge soup: deliberately, there is no separate bell/notification tray. The list ordering + hint-bar counter + palette ranking are the notification surface, keeping the quiet aesthetic intact.

10. Failure Recovery Behavior (mapped to flow-map failure paths)

Each flow-map failure path gets a command-first expression:

• Backend unreachable / WebSocket drop (heartbeat >10s): a slim banner replaces the hint bar: ⚠ Reconnecting to workspace… with auto-retry (exponential backoff). Last-known list state stays visible (rows dimmed). Launch/approve commands are disabled and the palette shows them grayed with (offline); jump/read commands still work against cached state.
• Agent process crash (exit ≠ 0): the agent’s row flips to an error dot and floats to top. Auto-restart runs for transient errors (up to 3). The palette surfaces restart <agent> and open terminal <agent> as top suggestions for that agent. Maps to Path D (recovery): jump to <agent> → focus mode shows error output / stack trace; ⌘K → retry (same prompt) or restart with "<new prompt>".
• Network tunnel drop: same reconnect banner; rows show tunnel reconnecting… in the one-line status. Agents unaffected (server-side). No command needed; auto-heals.
• Model key / rate-limit expiry: affected agent pauses, row shows paused: credential status. Palette surfaces open settings (S10) for that credential; after update, resume <agent> restores session state.
• GitHub OAuth token expired/revoked (401/403 on git op): affected agents pause; the palette top suggestion becomes re-authenticate github. Resumes automatically once a new token issues; no session state lost.
• Git conflict during agent work: agent pauses and requests approval with conflict details — surfaces as a waiting row. jump to <agent> → focus mode (terminal-primary for CLI tools) lets the user resolve in the terminal, or ⌘K → instruct "<resolution>" injects a resolution prompt.
• Browser/PWA crash: service worker reloads to the board with current server-canonical state; back-stack is reconstructed shallowly (board only). No data loss.
• S4 launch failure (tool not found / git error): the palette launch flow returns inline error text in the palette itself (✗ tool 'aider' not installed — try 'install tool aider' or pick another), with the failed command pre-filled for quick edit-and-retry. Tool-unavailable routes to open settings.

Re-plan trigger (per CLAUDE.md): if a failure recovery would require new structural work (not a clear command path above), the implementation stops and re-plans rather than improvising.

11. Page & Flow Changes vs. Flow-Map Baseline

• S3 board: baseline is a “responsive grid of agent cards.” V4 replaces it with a quiet minimal list (rows, not cards). Card-level rich previews are dropped from the fleet view (live stdout moves into focus mode only).
• S4 launch: baseline is a “centered modal with backdrop.” V4 replaces the modal with a command-palette launch (typed/guided grammar inside the ⌘K surface). No separate modal route.
• S5 + S6: baseline lists them as two screens with a Mode A/B toggle. V4 folds them into one focus-mode screen whose rendering is tool-adaptive (terminal-primary vs structured), per the brief’s confirmed reframe. The “Open Terminal” toggle from the baseline S5 footer is removed as a mode control; for API-native tools an “escape to raw” affordance may still exist but it is not a primary mode switch.
• Navigation model: baseline implies click-through routing. V4 introduces the palette + back-stack + focus-mode model (§12) as the spine.
• Notification surface: baseline implies an approval-queue badge in the header. V4 moves this into the hint-bar counter + palette ranking (no header badge tray).
• Header chrome: minimized — app name, the QR/“Open on Mobile” affordance, and settings move into palette commands (open settings, open on mobile) plus a minimal top bar; the board header is intentionally sparse to preserve the quiet aesthetic.

No upstream screen is removed; S7/S8/S9/S10 remain reachable as palette destinations. The flow-map’s tool-adaptive folding is carried as an amendment, not a silent edit to the approved doc.

12. Navigation Model (palette + back-stack + focus mode)

Three coordinated primitives:

1. Command palette (⌘K): the universal verb surface. Available everywhere (board and focus mode). It is context-aware: on the board it ranks fleet/launch verbs; in focus mode it ranks single-agent verbs (approve, retry, inject, stop, open terminal) and implicitly targets the focused agent.
2. Focus mode: opening an agent (jump to, Enter on a row, or push deep-link) covers the board with a full-attention single-agent view. This is the folded S5/S6 detail.
3. Back-stack: the board is pushed onto a navigation stack when focus mode opens. Esc (or clicking the breadcrumb Board / <agent>) pops back to the exact prior board state (scroll position, active filter, selection). Nested jumps (agent → terminal sub-view, if any) stack and pop in order. The back-stack is what makes deep-work-then-return feel instant and lossless — the explicit contrast with V2’s context-dropping route.

Inline filter (/): a lightweight, palette-adjacent affordance — pressing / on the board focuses an inline filter on the list (fuzzy match on name/repo/status) without opening the full palette, for fast narrowing. filter status:error via ⌘K does the same with explicit grammar.

Breadcrumb: focus mode shows a single breadcrumb (Board / agent-name) — both an orientation cue and a clickable back affordance (the fallback for users who don’t reach for Esc).

13. Screen-by-Screen Layout (regions & proportions)

S3 — Quiet Minimal List (board)

• Top bar (~48px): left: app mark + breadcrumb root Board. Right: a single ⌘K chip (clickable → opens palette) and an overflow ⋯ (settings, open-on-mobile/QR) — minimal, so the list dominates.
• List region (fills viewport): one row per agent, ~40–48px tall. Each row left-to-right: [status dot] agent-name · repo/branch · tool — one-line status · elapsed. Low chrome: no card borders, just a hairline row separator and a hover/selected highlight. No live stdout preview here (that lives in focus mode). Default sort error > waiting > running > idle; the active filter, if any, shows as a removable chip above the list.
• Status dot semantics: red = error, amber (subtle pulse) = waiting/approval, green = running, gray = idle, blue = starting.
• Hint bar (~28px, bottom, always visible): ⌘K Command · / Filter · ↵ Open · ? Help + right-aligned attention counter (2 waiting · 1 error) when applicable.
• Empty state: centered command prompt + suggested-command chips (§4) in place of the list.
• Proportions: list ≈ 88% of vertical space; top bar + hint bar ≈ 12%. Density is high but calm — many rows visible without scrolling (a 12-agent fleet fits on one desktop screen).

S4 — Palette Launch (overlay on board)

• Palette overlay: a centered, ~560px-wide command surface descending from the top (~12% from top), board dimmed behind. Single input line at top; ranked suggestion/result list below (max ~8 rows visible, scrollable).
• Launch flow within the palette: typing start agent switches the palette into a guided launch state: the input shows a structured template start agent on [repo ▸] with [prompt…] using [tool ▸]. Repo and tool segments are fuzzy-pickable inline (type to filter, Tab to advance segment); prompt is a free-text segment (Shift+Enter for multi-line). Enter fires. The palette stays the only surface — no separate modal.
• States (mapped to flow-map S4 matrix): Loading repos → repo segment shows a spinner; Launching → input line shows Starting agent… with the segments locked; Error → inline ✗ … line beneath the input with the command pre-filled for edit; Tool unavailable → inline warning + install tool <x> suggestion.

S5/S6 — Focus Mode (folded, tool-adaptive detail)

• Breadcrumb bar (~40px): Board / agent-name (clickable back) · status dot + label · tool · repo/branch · elapsed. Right: Esc to return hint.
• Primary region (fills the rest):
  • CLI tools → terminal-primary: a near-full-width xterm.js terminal over WebSocket is the interface. Structured chrome is a thin wrapper only (the breadcrumb bar above + an inline approval strip when waiting). Keystroke echo target sub-100ms (intrinsic, per open question — not a toggle).
  • API-native tools → structured: the same region renders the parsed activity stream (steps, file-change list, progress) instead of a terminal. Same breadcrumb chrome, same command palette.
• Inline approval (S7 touchpoint): when the agent is waiting, an approval strip appears in-flow (diff preview, Approve/Reject) — keyboard-reachable, and also driveable via ⌘K → approve.
• Footer / command line (~32px): an inline prompt-injection field for the focused agent (the keyboard-native user’s “talk to the agent” line) + the hint bar showing focus-mode shortcuts (⌘K · ↵ approve · esc back · ⌃c stop).
• Proportions: terminal/structured region ≈ 86%; breadcrumb ≈ 7%; footer/hint ≈ 7%. Maximally given to the work surface.

14. Key Components & Controls

Command palette (the centerpiece). Grammar is verb-first, fuzzy-tolerant, and forgiving (partial matches resolve to ranked suggestions). Core grammar with examples:

Palette behaviors: discovery mode (grouped suggestions when empty), context-aware ranking (pending approvals/errors surface first), inline errors with command pre-fill, segment-based guided launch, recent-command history (Up arrow recalls last commands).

• Quiet list rows — status dot + name + repo + tool + one-line status + elapsed; keyboard-selectable (↑/↓), Enter opens.
• Hint bar — always-visible context shortcut strip + attention counter. The primary discoverability mitigation.
• ? Help overlay — searchable, categorized full command reference.
• Inline filter (/) — fast list narrowing without full palette.
• Focus-mode terminal / structured stream — tool-adaptive primary surface.
• Inline approval strip — in-flow diff + approve/reject within focus mode.
• Suggested-command chips — empty-state and onboarding scaffolding.

15. Button & Link Behavior (and keyboard shortcuts)

The design is keyboard-first but every command has a fallback clickable affordance (anti-discoverability-trap principle):

• ⌘K / Ctrl+K — open command palette (global). The ⌘K chip in the top bar is the clickable equivalent.
• / — focus inline list filter (board).
• ↑ / ↓ — move row selection (board) or palette suggestion selection.
• ↵ Enter — open selected agent (board) / execute selected command (palette) / approve focused approval.
• Esc — close palette if open, else pop focus mode back to board (back-stack). The breadcrumb Board / is the clickable equivalent.
• ? — open help overlay.
• ⌃C (Ctrl+C) — stop focused agent (focus mode), with confirm.
• Tab / Shift+Tab — advance/retreat segments in the guided launch flow.
• Up (empty palette) — recall previous command from history.
• g then b (chord) — go to board from anywhere (vim-style escape hatch).
• Attention counter token — clickable/Enter → approve next walk.
• Push notification deep link — opens focus mode for the target agent.
• Suggested-command chip — click pre-fills palette (teaches grammar).

Every keyboard action has a visible, pointer-accessible twin so the UI is never only discoverable by memory.

16. Spatial Density, Sizing, Hierarchy

• Density: high but calm. The quiet list packs many agents per screen (40–48px rows) without the visual weight of cards — a 12-agent fleet is one glance, no scroll, on desktop. Focus mode is the opposite: a single agent given ~86% of the viewport.
• Hierarchy: driven by position + a single accent dot, not by size or color blocks. Sort order (error > waiting > running > idle) carries priority; the status dot is the only saturated color in a row. The palette, when open, is the single dominant element (board dims behind it).
• Sizing: body text ~14px in rows, monospace ~13px in the terminal; the palette input is larger (~16px) to signal “you are typing a command now.” Hit targets meet 44px minimum on touch (rows expand to ~52px on coarse pointers).
• Restraint: color is reserved almost entirely for status dots and inline approval/error accents (palette --accent:#4dabf7 for the active palette/selection; red/amber/green for status). The result reads like a well-configured terminal — information-dense, low-noise.

17. Responsive Behavior at 3 Breakpoints

• Mobile (≤640px): the ⌘K affordance is replaced by a persistent bottom command bar — a tap-to-open command surface pinned to the bottom (thumb-reachable), opening the same palette grammar full-width as a bottom sheet. The list stays single-column rows; the hint bar merges into the command bar. Focus mode goes full-screen; terminal is read-mostly with an open on desktop handoff for heavy typing (typed commands on a phone keyboard are acknowledged as awkward — see Risks). Approvals and approve next are the optimized mobile path (large tap targets in the bottom sheet). Push → focus mode deep link works as on desktop.
• Tablet (≤1024px): desktop list + ⌘K palette retained (most tablets pair a keyboard); the bottom command bar appears only when no hardware keyboard is detected / on touch-primary use. Rows expand to ~52px for touch. Focus mode is full-width; the inline approval strip uses larger tap targets.
• Desktop (>1024px): the home turf. Full ⌘K palette, dense quiet list (12 agents on one screen), focus mode with terminal-primary rendering and full keyboard grammar. Hint bar always visible. This breakpoint is where Command-First is strongest.

The device-posture axis for this variation is deliberately keyboard-desktop-first with a mobile bottom-bar fallback — distinct from V5’s mobile-first and V1’s desktop-dense-table.

18. Visual Tone

Terminal-native, quiet, confident, low-noise. Dark by default (house palette: --bg:#1a1a2e; --card:#16213e; --border:#2a2a4a; --accent:#4dabf7; --text:#e0e0e0; --muted:#8b8fa3). The aesthetic evokes a well-tuned tmux/Raycast/editor-command-palette: monospace accents, hairline separators, status as single colored dots, the palette as the one moment of focused brightness. Motion is near-absent except the subtle pulse on waiting rows. The feeling is fast and unobtrusive — the UI defers to the work.

19. Strengths

• Velocity for power users: launch, filter, jump, and approve are a few keystrokes — no mouse hunting, no modal context-switches. Fanning out 3 agents (Path C) is the fastest of all five variations.
• Unified mental model: one palette grammar spans orchestration and deep-work; the user learns one verb set, not several UIs.
• Lossless deep-work return: the back-stack restores exact board state on Esc — superior deep-work continuity to V2 (route) and V3 (drawer-over-moving-board).
• Calm density: 12 agents on one screen with minimal visual noise; the quiet list scales better at high agent counts than card layouts that waste space.
• Natural CLI fit: the keyboard ethos pairs cleanly with terminal-primary focus mode — the target user already lives in a terminal.
• Quiet-but-loud-when-needed: priority sort + hint-bar counter + palette ranking surface errors/approvals without a noisy notification tray.

20. Risks & Failure Modes (with mitigations)

• Discoverability (the core risk): a command-first UI can hide capability. Mitigations: always-visible hint bar; palette discovery mode (grouped suggestions, no memorization required); ? help overlay one key away; suggested-command chips in onboarding/empty state; context-aware palette ranking; and every command has a clickable twin (⌘K chip, breadcrumb back, attention-counter token, approval strip). The UI is never only keyboard-discoverable.
• Weak fleet glanceability: the quiet list lacks rich live previews; you can’t see what each agent is doing without opening it. Mitigations: the one-line status per row carries the latest parsed stdout summary; priority sort floats what matters; the hint-bar counter quantifies attention. Users who need rich fleet previews are explicitly better served by V2/V5 — this is an accepted tradeoff, surfaced for the variant evaluation.
• Awkward mobile command-typing: typing structured commands on a phone keyboard is slow. Mitigations: the bottom command bar emphasizes tap-driven suggestions (approve next, jump to, recipes) over free typing; mobile is positioned as a glance-and-approve device, with open on desktop handoff for heavy terminal work; the palette’s discovery mode means mobile users mostly tap ranked suggestions rather than type.
• Grammar drift / forgotten verbs: users may forget exact syntax. Mitigations: fuzzy/partial matching, command history (Up arrow), forgiving inline error messages with pre-filled corrections.
• Terminal latency (bounding open question): focus mode for CLI tools depends on sub-100ms xterm.js echo over the tunnel. If latency is poor, deep terminal interaction degrades. Mitigation/posture: structured rendering is the fallback for API tools; for CLI tools, prompt-injection via the footer command line is a lower-latency path than raw keystroke typing when the tunnel is slow. This stays an empirical open question, not silently assumed solved.
• stdout-parsing reliability (bounding open question): the one-line row status leans on parsed stdout; unreliable parsing weakens the quiet list. Mitigation: rows degrade gracefully to raw last-line + status dot when structured parsing is unavailable, rather than promising structured status the parser can’t deliver.
• IDE/code-server: deliberately out of scope for this variation — no command-first argument compels an in-browser IDE here; the terminal-primary focus mode covers the power-user escape hatch. (Honors the brief’s default-out-of-scope stance.)

21. Implementation Complexity

Medium (matches the brief’s rating). Drivers:

• Higher than baseline: the command palette is the most involved component — fuzzy matching, grammar parser, guided segmented launch flow, context-aware ranking, command history, inline error handling. The back-stack navigation (lossless board-state restore) and the always-visible context-aware hint bar add coordination logic.
• At parity with baseline: the quiet list is simpler to build than rich card grids (low chrome, no per-card live preview rendering). Focus mode reuses the same tool-adaptive xterm.js / structured-stream components every variation needs (shared cost, not V4-specific).
• Shared cost (not V4-specific): WebSocket state sync, xterm.js terminal, stdout parsing, push notifications — common to all five.
• Net: the palette + back-stack are the incremental V4 investment; everything else is shared or simpler. No code-server, no IDE runtime. Medium overall.

22. Prototype Scope

For the variant-evaluation build (static-leaning HTML/CSS + light JS, dark house palette):

• S3 quiet list with ~8–12 seeded agents across mixed statuses, correct priority sort, status dots, one-line statuses, hint bar with attention counter.
• Empty state with command prompt + suggested-command chips.
• ⌘K command palette — working open/close, fuzzy filtering over a seeded command set, discovery mode (grouped suggestions), and the guided launch flow (segmented start agent on … with … using …) producing a new list row.
• Inline filter (/) narrowing the list.
• Focus mode for at least two agents: one terminal-primary (xterm.js or a faked terminal pane) and one structured (parsed activity stream) — demonstrating tool-adaptive rendering with no user toggle. Include the breadcrumb + back-stack Esc return and an inline approval strip.
• Hint bar updating between board and focus-mode contexts.
• Mobile breakpoint (≤640px) with the persistent bottom command bar opening the same palette as a bottom sheet.
• ? help overlay stub.

Out of prototype scope: real WebSocket backend, real tool processes, push delivery, S8/S9/S10 full screens (link/stub only), QR generation.

23. Readiness Signal for /ui-interview

This spec is build-grade and ready for prototype + /ui-interview on the v4-command-first branch. It fully specifies: the two-layer surface (S3/S4 orchestration + folded tool-adaptive S5/S6 deep-work), the palette/back-stack/focus-mode navigation spine, the command grammar with concrete examples, the discoverability mitigations (hint bar, discovery mode, help, clickable twins), the quiet-list notification model, failure-path mappings to the flow-map, three responsive breakpoints with the mobile bottom command bar, density/hierarchy/visual tone, and explicit contrast against all four siblings. Single-user scope (sharing/permissions N/A) and the bounding open questions (terminal latency, stdout-parsing reliability, IDE out-of-scope) are honored, not assumed away. Recommended next step per the brief: build serially → /uat --variant-evaluation → /consolidate-variations, or /ui-interview v4-command-first if this branch is taken to visual mockup directly.

1. Name & Thesis

Glanceable Stream. The fleet is a single prioritized vertical feed — the thing that needs you is at the top, everything calm sinks below the fold. The product is designed phone-up: the canonical posture is the conductor standing in line for coffee, thumb on the screen, glancing at “what needs me right now.” Approvals and errors pin to the top; waiting, running, and idle agents stack beneath in descending urgency. Interaction is big tap targets, swipe actions (swipe-to-approve, swipe-to-stop), and pull-to-refresh. Launching a new agent is not filling a blank form — it is duplicate-from-template: pick a saved recipe (repo + tool + prompt template) from a quick-start sheet and go. Drilling into an agent opens a full-screen sheet; on a phone its terminal is read-mostly with a one-tap “open on desktop” handoff, because a live terminal is genuinely hard to drive with a thumb.

The thesis in one line: the conductor whose laptop is closed and whose launches are mostly re-runs of known recipes should be able to run the whole monitor→approve→launch loop one-handed, in under a minute, from a feed that always shows the right thing first.

2. Parent User Flow & Branch Relationship

Position in the flow-map

V5 covers the monitoring-start branch: Happy Path steps 3–6 (S3 Agent Board → S4 Start Agent → S3 new card → S5/S6 Interact) plus Path C “Parallel Sprint” (launch agent #2/#3, monitor all, round-robin approvals). It is the monitor + launch surface of the product.

Two-layer obligation (hard constraint)

Per the brief’s confirmed reframe, this is a two-layer surface, not one job:

• Orchestration layer (S3/S4) — the feed itself + the template quick-start sheet. Fleet-level: scan what needs you, fan out parallel agents, launch fast.
• Deep-work layer (S5/S6) — the full-screen detail sheet for a single agent. Folded + tool-adaptive (see §13).

V5 serves both. What V5 contrasts against siblings is how the orchestration layer connects to the deep-work layer: here, a feed item taps open into a full-screen sheet that owns the viewport, then dismisses back to the feed (vs. V1’s persistent split-pane, V2’s full-page route, V3’s drawer-over-board, V4’s focus-mode back-stack).

Boundary vs. sibling branches (explicit — do not redesign these)

V5 lives next to two conceptually overlapping sibling branches. The boundary is deliberate:

• approval branch (Path B + S7) — owns the deep approval experience: the rich diff viewer, risk assessment, modify-prompt, reject-with-reason, batch/queue policy, push-notification-to-approval deep links. V5 owns only the approval’s presence in the monitor feed: the pinned-top feed item, the swipe-to-approve fast path, and the one-tap “expand” that hands off into the approval branch’s S7 surface. V5 does not redesign the diff viewer or the approval-queue policy — it references them. When a V5 feed item needs more than swipe-approve, it opens the approval branch’s S7 card; V5’s job ends at “surfaced it first and made the yes/no one swipe.”
• device-handoff branch (Paths E + F, including qr-handoff) — owns cross-device continuity and QR handoff. V5’s mobile-terminal “open on desktop” affordance is an entry point into that branch, not a re-implementation. V5 emits the handoff intent (deep link / QR); the device-handoff branch owns the QR generation, one-time token, and pre-authenticated deep-link plumbing. V5 references it; it does not own it.

If a behavior is deep-diff, queue-policy, QR-token, or recap-timeline logic, it belongs to a sibling branch. V5 owns the feed (monitor) and the template launch, and the thin connective tissue that surfaces sibling surfaces.

3. Target User Fit

Best fit: the “closed laptop, checked from phone, 3 PRs ready” conductor — the aha-moment persona at the deliberately phone-up end of the device-posture axis. This is the solo Agent Conductor (5–12 agents, 1–3 repos) whose day looks like:

• Most launches are re-runs of known recipes (“run the test-fix agent on repo X,” “kick the dependency-bump recipe on the two service repos”) — novel from-scratch prompts are the exception, not the rule.
• The dominant interaction is triage on the go: a notification fires, they glance, they swipe-approve or swipe-stop, they pocket the phone. Total interaction budget: tens of seconds.
• They reach a desktop for deep work — reading a long terminal, resolving a git conflict, reviewing a real diff — and V5 hands them there explicitly rather than pretending a phone is a workstation.

Poor fit (state honestly): the keyboard-at-max-density power user who wants 12 agents in one dense viewport with split-pane drill-in and never leaves the desk — that user is V1 Operator Console. The command-native dev who lives in ⌘K is V4. V5 deliberately trades desktop multitasking density for one-handed glanceability. See §20 risks.

4. Onboarding / Activation Model

V5 inherits account/infra onboarding from the onboarding branch (Path A: S2 Setup Wizard → provision → health check → S10 summary → S3). V5 owns only the first-run state of the monitor+launch surface it lands on.

Empty feed (first arrival at S3)

The flow-map’s S3 “Empty” state (“Start your first agent” CTA) becomes a feed zero-state:

• A single full-width primary card: “No agents running. Start your first one.” with a large Start agent button that opens the template quick-start sheet (§13, S4) in “new from scratch” mode (no recipes exist yet).
• Below it, a dismissible explainer strip: a one-line “This feed shows what needs you first — approvals and errors pin to the top” so the prioritization model is taught, not discovered cold.

First recipe (the activation moment)

The activation event for V5 specifically is saving the first recipe. After the user’s first successful from-scratch launch, the launch-confirmation toast offers “Save as recipe” (repo + tool + prompt template, with the variable parts of the prompt optionally tokenized). Once one recipe exists, the quick-start sheet flips to recipe-first (duplicate-from-template primary, from-scratch secondary). This is the loop the persona is built for, so onboarding nudges toward it early.

PWA install prompt

• V5 is an installable web PWA (locked constraint — all web PWA). On first mobile visit that did not arrive via the device-handoff QR path (which owns its own install prompt per the flow-map’s qr-handoff step 7), V5 surfaces a non-blocking install banner after the first meaningful action (first launch or first approval), framed as “Install to get push notifications when an agent needs you.”
• The install pitch is tied to push: the value of installing is the return-use loop (§9), so the prompt is deferred until the user has felt the loop once. iOS Safari’s Web Push limitations are an open risk (flow-map Open Q #3) — see §9 fallback.

5. Typical Workflow Sequence (the phone-up monitor→approve→launch loop)

The canonical V5 session, one-handed on a phone:

1. Push fires — “Agent test-fix needs approval” (or “Agent deploy-prep errored”). User taps the notification. (Push + deep-link delivery is shared with approval/device-handoff; V5’s job starts at the feed.)
2. Feed opens, urgent item already on top — PWA resolves to S3. The agent that fired is the top pinned feed item (approval or error), visually distinct. No scrolling, no hunting.
3. Glance — the pinned item shows agent name, status, repo, the one-line “why it needs you” (e.g., “wants to run db:migrate” or “git merge conflict in auth.ts”), and a wait-duration timer.
4. Decide by swipe — for a clear yes: swipe right → approve. For a clear stop: swipe left → stop/reject. Done; the item animates out and the next-most-urgent item rises. For anything needing thought, tap to open the full-screen sheet (→ hands into approval branch S7 for the real diff).
5. Scan the rest — below the pinned zone, the user thumbs down the feed: waiting → running → idle. Live one-line stdout under each running item gives a calm pulse-check. Pull-to-refresh at top forces a state resync (also the manual escape hatch if the WebSocket looked stale).
6. Launch a re-run — tap the persistent Launch action (bottom nav, §12). The template quick-start sheet slides up; the user taps a saved recipe (e.g., “lint-fix · repo-api · CLI”), optionally tweaks the one tokenized prompt field, taps Start. Sheet dismisses; a new “starting” feed item appears (transitions to running within seconds, live stdout begins).
7. Parallel fan-out (Path C) — repeat step 6 for repo #2 and #3 from recipes; the feed now carries 3+ running items plus whatever pinned approvals arrive. Round-robin approvals are handled by repeating steps 2–4 as pushes land.
8. Drop the phone — agents run on managed infra; the loop is closed. Deep review (real diffs, terminal debugging) is deferred to a desktop via the handoff (§13), not attempted on the phone.

Steps 1, 4-into-S7, and the desktop handoff are boundaries: V5 surfaces and routes; the approval and device-handoff branches own what happens past the boundary.

6. Progression Model — and Explicit Contrast With the Four Siblings

How the user advances in V5

Progression is gravity-driven, not navigation-driven. The user does not “go somewhere” to find work; the feed brings the work to the top. Advancement is:

1. Top of feed (act on what’s pinned) →
2. down the feed (scan calm agents) →
3. launch (template sheet, return to feed) →
4. drill (full-screen sheet only when an item demands it) →
5. dismiss back to feed.

The feed is always the home position. Every drill-in is a temporary full-screen overlay that returns to the same feed scroll state. The mental model is a prioritized inbox: you work the top, things resolve and disappear, new things arrive at the top.

Explicit contrast with the other four variations

The throughline: V5 is the only variation that assumes you are not looking at the screen continuously. It optimizes for the glance, not the session. The others assume an attentive operator at a desk; V5 assumes a distracted thumb and makes the right thing rise to it.

7. Sharing & Collaboration Model

N/A — single-user personal workstation. Per the locked scope constraint, gblock-party personal-workstation is a solo dogfood environment with no second human. There is no sharing of feeds, agents, recipes, or approvals; no shared views, no comments, no handoff-to-a-teammate. The only “handoff” in V5 is device-to-device for the same user (the device-handoff branch), which is continuity, not collaboration. No collaboration affordances are invented.

8. Permissions Model

N/A — single-user personal workstation. There are no roles, no per-agent ACLs, no shared-resource permissions, no multi-tenant boundaries. The single user owns everything. The only authorization in the system is GitHub OAuth identity + repo scopes (owned upstream by S1/onboarding), which is the user authenticating themselves to their own repos — not a permissions model over other users. V5 invents no permissions surface.

9. Return-Use & Notification Model (the strongest of the set)

This is V5’s signature strength — it is built for return-use, because the persona’s defining act is coming back to a closed-laptop fleet from a phone.

Pinned approvals & errors (the always-right-first feed)

The feed’s sort is V5’s reworking of the flow-map default (error > waiting > running > idle — explicitly reworkable per brief):

• Pinned zone (top, visually separated, sticky): items needing the user — errors and pending approvals — sorted by urgency (error first, then approval by longest wait). This zone is what the user sees on every return, above the fold, guaranteed.
• Stream zone (scrollable below): waiting → running → idle, each with live one-line stdout and elapsed time.
• On return, the pinned zone is the answer to “what needs me?” — no recap screen required for the common case (the full S8 recap belongs to device-handoff for long-absence catch-up).

Pull-to-refresh

State is server-canonical over WebSocket and reflows automatically. Pull-to-refresh is the explicit user gesture for “resync now, I don’t trust what I’m seeing” — it forces a fresh state pull and reconnect, and is the natural mobile recovery action when the connection banner is showing (§10). It doubles as the “I just woke the phone” reassurance gesture.

Push notifications (installed PWA)

• The PWA is installable; install is pitched explicitly to unlock push (§4). Push events: approval requested, agent errored, task completed, key/token expiry.
• A push deep-links to the feed with the relevant item pinned top (or, for an approval, can deep-link straight into the approval branch’s S7 card — that routing is shared, V5 just renders the landing feed state).
• Fallback for unreliable Web Push (flow-map Open Q #3, esp. iOS Safari): V5 degrades gracefully — if push is unavailable/denied, the pinned zone + pull-to-refresh still deliver the full triage value on manual open, and the install banner is suppressed rather than nagging. (Alternative channels — SMS/Telegram/email — are an upstream/notification-policy concern, not a V5 layout decision; V5 references the open question, does not resolve it.)

Why “strongest of the set”: V1/V4 optimize the attentive desktop session; V2/V3 are co-equal/desktop-reflow. Only V5 makes the return glance the primary designed-for moment — pinned-top + push + pull-to-refresh is a return-use loop the others treat as secondary.

10. Failure Recovery Behavior (mapped to flow-map failure paths)

V5’s core failure principle: anything that needs the user pins to the top of the feed, in the same pinned zone as approvals, with an error treatment. The user never has to go looking for a failure — failures come to them. Mapping the flow-map’s Failure & Recovery table:

Recovery ergonomics: because failures share the pinned zone with approvals, the same swipe vocabulary applies where safe — e.g., swipe-to-retry on a crashed-agent item (with a confirm for destructive cases). Anything requiring real inspection (stack traces, conflict diffs, terminals) is a tap into the full-screen sheet, and on a phone routes to desktop handoff rather than cramming it onto the small screen.

11. Page & Flow Changes vs. the Flow-Map Baseline

No new screens are invented beyond folding S5/S6 and re-skinning S3/S4 — V5 is a re-presentation of the in-scope screens, not an expansion.

12. Navigation Model

Mobile-first navigation; three primitives only:

1. The feed (home). Vertical scroll. Sticky pinned zone at top. Pull-to-refresh at the top edge. This is the always-return-to surface.
2. Full-screen sheets. Two kinds — the template quick-start sheet (launch) and the agent detail sheet (drill-in). Both slide up over the feed, own the viewport, and dismiss (swipe-down on the sheet handle, or a top-left Back/Close) back to the exact feed scroll position. No nested deep stacks — the model is feed ↔ one sheet, never sheet-on-sheet (the only exception: detail sheet → into a sibling-branch surface like S7/S9, which is a branch boundary, not a V5 nav layer).
3. Bottom nav (persistent, thumb-zone). Three to four targets, mobile-first ergonomics:
   • Feed (home / fleet)
   • Launch (opens template quick-start sheet) — center, emphasized
   • Approvals (jumps the feed to / filters the pinned approval items; badge count) — note the deep approval UX is the approval branch; this is just the fast jump
   • Settings (→ S10, sibling settings branch)

On desktop (>1024) the bottom nav migrates to a slim left rail or top bar (same four targets), and sheets become centered overlays rather than full-bleed (§17). The navigation vocabulary stays identical across breakpoints — only the chrome position changes — so the mental model is portable when the user moves phone→desktop.

13. Screen-by-Screen Layout (regions & proportions)

Dark scheme per house style (--bg:#1a1a2e; --card:#16213e; --border:#2a2a4a; --accent:#4dabf7; --text:#e0e0e0; --muted:#8b8fa3). Proportions given for the primary mobile ≤640 viewport; desktop deltas in §17.

S3 — Agent Board (the feed)

+-------------------------------------------+
| [= workspace]          [approvals .3] [gear]|  Header  ~7% h
+-------------------------------------------+
| (pull-to-refresh affordance on drag)      |
+-------------------------------------------+
| ## PINNED ZONE (sticky) ##                |  Pinned
| +-------------------------------------+   |  zone:
| | [STOP] deploy-prep . repo-api       |   |  grows to
| | git conflict in auth.ts . 4m        |   |  fit, caps
| |   < swipe: retry      stop >         |   |  at ~45% h
| +-------------------------------------+   |  then
| | [PAUSE] test-fix . repo-web         |   |  scrolls
| | wants db:migrate . waiting 2m       |   |  internally
| |   < swipe: approve    reject >       |   |
| +-------------------------------------+   |
+-------------------------------------------+
| STREAM ZONE (scroll)                      |  Stream
| +-------------------------------------+   |  zone:
| | > lint-fix . repo-api . running 12m |   |  fills
| |   $ applying fix to eslintrc...     |   |  remainder
| +-------------------------------------+   |  (one-line
| | > docs-gen . repo-web . running 3m  |   |  live
| |   $ writing README section...       |   |  stdout per
| +-------------------------------------+   |  running
| | o refactor . repo-cli . idle        |   |  item)
| +-------------------------------------+   |
+-------------------------------------------+
|   [Feed]   [ + Launch ]   [Approvals] [gear]| Bottom nav ~9% h
+-------------------------------------------+

• Header (~7%): workspace menu, approvals badge (count), settings gear. (QR/“Open on Mobile” lives here too but is the device-handoff branch’s surface.)
• Pinned zone (sticky, grows to content, caps ~45% then internally scrolls): errors + pending approvals, error-first then approval-by-wait. Each item: status glyph, agent · repo, the “why it needs you” line, wait timer, swipe affordance hints. Big tap target (whole row).
• Stream zone (remaining height, scrollable): waiting → running → idle; running items carry one-line live stdout in monospace --muted.
• Bottom nav (~9%, thumb zone): Feed · Launch (emphasized center) · Approvals · Settings.
• Empty/Connection-lost states per §4/§10.

S4 — Template Quick-Start Sheet (launch)

Full-height bottom sheet sliding up over the feed (mobile); centered overlay (desktop).

+-------------------------------------------+
|  ___ (drag handle)                  [x]   |
|  Start an agent                           |
+-------------------------------------------+
|  YOUR RECIPES                             |  Recipe
|  +---------------+ +---------------+      |  grid/list:
|  | lint-fix      | | test-fix      |      |  primary,
|  | repo-api.CLI  | | repo-web.CLI  |      |  ~60% h
|  +---------------+ +---------------+      |
|  | dep-bump      | | docs-gen      |      |  tap a
|  | repo-cli.API  | | repo-web.CLI  |      |  recipe ->
|  +---------------+ +---------------+      |  prefilled
+-------------------------------------------+
|  -> selected: lint-fix                    |  Confirm
|  prompt: "fix lint in {{path}}"  [edit]   |  strip:
|  +-------------------------------------+  |  one
|  | {{path}} = src/                     |  |  tokenized
|  +-------------------------------------+  |  field
|           [  Start agent  ]               |  editable
+-------------------------------------------+
|  + New from scratch  (secondary)          |  Secondary
+-------------------------------------------+

• Recipe picker (primary, ~60%): saved recipes as big tap cards (name, repo·tool). Tap → prefilled.
• Confirm strip: shows the resolved recipe; the one tokenized prompt variable is inline-editable (the common “same recipe, different path/branch” tweak) without reopening a full form. Big Start button.
• “New from scratch” (secondary, bottom): opens the full repo/tool/prompt form (the flow-map’s blank S4) for novel launches — deliberately demoted.
• S4 states (Loading repos / Launching / Error / Tool-unavailable) per flow-map matrix, rendered inside the sheet.

Full-Screen Detail Sheet — folded S5/S6 (tool-adaptive)

One sheet, no Mode A/B toggle. Primary rendering is decided by the agent’s tool integration pattern:

+-------------------------------------------+
| [< Back]  test-fix . repo-web . > 12m [..]|  Sheet header
+-------------------------------------------+
|  STRUCTURED CHROME (always)               |  ~30-40%
|  - progress / current step                |  parsed
|  - file-change list                       |  status
|  - inline approval card (when waiting)     |  (Multica)
+-------------------------------------------+
|  PRIMARY RENDER (tool-adaptive)           |
|   CLI tool -> terminal pane                |  remainder
|     [phone: READ-MOSTLY, scrollback only] |
|     +---------------------------------+   |
|     | $ npm test                      |   |
|     | + 42 passing  x 1 failing       |   |
|     | ...live xterm.js (read) ...     |   |
|     +---------------------------------+   |
|     [ Open on desktop to type ]  <-handoff|
|   API-native tool -> structured detail     |
|     (no terminal; rich parsed view)        |
+-------------------------------------------+
|  [ Approve ] [ Inject prompt ] [ Stop ]   |  Action bar
+-------------------------------------------+

• Structured chrome (always present, ~top third): agent header, progress/current-step, file-change list, and an inline approval card when the agent is Waiting for Input (the lightweight in-context approve; the deep diff is the approval branch).
• Primary render (tool-adaptive, remainder):
  • CLI tools (Claude Code CLI, Codex, Aider, Continue, Cline, Copilot CLI, Augment, Cursor worker) → terminal-primary (xterm.js over WebSocket) wrapped in the structured chrome. On a phone the terminal is READ-MOSTLY: full scrollback, live output, but no expectation of comfortable typing — a prominent “Open on desktop to type” button emits the device-handoff intent (deep link / QR) so interactive work moves to a real keyboard. On desktop the same pane is fully interactive (type commands, key input), targeting the sub-100ms echo budget.
  • API-native tools (Claude Agent SDK) → structured detail (no terminal at all; the parsed view is the interface).
• Action bar (bottom): Approve / Inject prompt / Stop (and Retry/Restart/Open-terminal in Error state per S5/S6 matrices). On phone these are large tap targets; “open terminal” on phone = the desktop handoff.

Open-question alignment: mobile read-mostly terminal directly hedges the terminal-latency open question (flow-map Open Q #1) — we don’t bet the phone experience on sub-100ms keystroke echo; we bet it on reading, and route typing to desktop. stdout-parsing reliability (Open Q #2) bounds how much the structured chrome can promise per tool; where parsing is thin, the chrome degrades to “raw stdout tail” rather than over-promising structure. code-server/IDE (Open Q #4) is out of scope for V5 — V5 makes no deliberate case for an in-feed IDE; the “go deeper than a terminal” answer is the desktop handoff, not a browser IDE.

14. Key Components & Controls

• Feed item (row). The atomic unit. Full-width tap target; status glyph + color, agent · repo, context line, timer; running items add one-line live stdout. Three classes: pinned-error, pinned-approval, stream (waiting/running/idle). Swipe-enabled.
• Pinned zone. Sticky, internally scrollable container; auto-populated by error + approval; the heart of return-use (§9) and failure recovery (§10).
• Swipe action layer. Per-item left/right swipe reveals contextual actions (see §15). Color-coded (approve=green/--accent, reject/stop=red), with confirm for destructive actions.
• Pull-to-refresh. Top-edge drag → resync/reconnect.
• Recipe / template model. A recipe = saved {repo, tool, prompt-template} with optional tokenized variables ({{path}}, {{branch}}). Created via “Save as recipe” post-launch (§4); the primary launch path. Editable/deletable from the quick-start sheet or settings.
• Template quick-start sheet (S4). Recipe-first launch surface; tokenized-field inline edit; “new from scratch” secondary.
• Full-screen detail sheet (folded S5/S6). Tool-adaptive render; structured chrome + terminal/structured primary; read-mostly mobile terminal; desktop-handoff button.
• Bottom nav (mobile) / left-rail (desktop). Feed · Launch · Approvals · Settings.
• Connection banner. Top sticky reconnect indicator.
• Push / install banner. Deferred, push-pitched install prompt (§4).

Referenced-but-not-owned components (sibling branches): the deep diff viewer / risk-rated approval card (approval), the QR / pre-authed deep-link generator (device-handoff), the recap timeline S8 (device-handoff), S9 diff/merge (diff-review), S10 settings (settings).

15. Button & Link Behavior (swipe gestures + tap targets)

Swipe gestures (per feed item)

• Swipes are revealable (partial swipe shows the action + color before commit) so they’re discoverable and reversible; a full swipe commits; a confirm gates destructive ones.
• Optimistic UI: a swipe-approve resolves immediately and the item animates out; if the server rejects (concurrent-device race, §10) a toast restores/explains.

Tap targets & links

• Every feed row is a full-width tap → detail sheet. Minimum 44–48px touch height; running rows taller to fit stdout.
• Bottom-nav targets sit in the thumb zone; Launch is the emphasized center action.
• In-sheet buttons (Approve / Inject / Stop / Start / Retry) are large, color-semantic, single-purpose.
• “Open on desktop” (terminal handoff) is a labeled button that emits the device-handoff deep-link/QR intent — it is a link into a sibling branch, not an in-V5 mode.
• Pull-to-refresh is the only “hidden” gesture and is taught in the empty-state explainer (§4).
• No hover-dependent controls anywhere (touch-first); desktop adds hover affordances as enhancement only.

16. Spatial Density, Sizing, Hierarchy

• Low-to-medium density, generous vertical rhythm. One column, big rows, comfortable spacing — the opposite of V1’s NOC density. Sizing is tuned so a phone shows roughly 3–5 items per fold, enough to triage without scrolling for the pinned case.
• Hierarchy by vertical position + treatment. The single strongest signal is “where is it in the feed” — top = needs you. Reinforced by: error/approval items get a colored left-edge accent and slightly taller/heavier treatment; running items are calm (--muted stdout); idle items are dimmed. The pinned/stream divider is an explicit visual seam.
• Type scale: agent name = primary, repo·tool = secondary --muted, context line = readable body, stdout = monospace --muted small. Status conveyed by glyph + color + label (never color alone — accessibility).
• Touch sizing: ≥44px targets, swipe zones full-row, nav in thumb reach. Density is deliberately not configurable on mobile (one honest phone density); desktop gains a denser optional second pane (§17) for users who want more on screen.

17. Responsive Behavior at Three Breakpoints

Mobile ≤640 (primary, the design center):

• Single full-width feed; sticky pinned zone; bottom nav in thumb zone; sheets are full-bleed; terminal is read-mostly + desktop handoff; pull-to-refresh active. Everything above describes this breakpoint.

Tablet ≤1024:

• Still one centered feed column (capped readable width, ~560–640px, centered with quiet gutters) — V5 does not sprout a grid; the feed identity is preserved. Bottom nav may migrate to a top bar or stay bottom depending on orientation. Sheets become large centered overlays rather than full-bleed. Terminal is interactive if a hardware keyboard is present, else still read-mostly + handoff. Swipe + tap retained (touch tablets).

Desktop >1024 (centered feed + optional second pane):

• Centered single-column feed remains the spine (capped width, centered) — V5 stays a feed on desktop, deliberately not a dense table (that’s V1). Nav migrates to a slim left rail / top bar.
• Optional second pane: the user may open a detail in a right-hand companion pane instead of a full overlay, so on a big screen you can keep the feed in view while reading one agent — a concession to desktop multitasking without abandoning the feed model. The pane is optional and dismissible; the default remains feed-centric.
• Terminal is fully interactive here (type commands, key input; sub-100ms echo target). The “open on desktop” handoff from a phone lands here — desktop is where deep terminal/diff work happens.
• Swipe gestures gracefully gain click-equivalent buttons (revealed on hover/focus) since desktop has no swipe; all swipe actions have a visible button fallback.

The responsive story is a posture gradient, not a layout swap: phone = glance & route, desktop = read & act deeply. Same feed, same nav vocabulary, progressively more capable as the screen and input grow.

18. Visual Tone

Calm, focused, inbox-like. Dark house palette throughout (--bg/--card/--border/--accent/--text/--muted). The feeling target is “a quiet notification feed that lights up only when it matters” — most of the screen is calm --muted running/idle items; the pinned zone is where color and weight concentrate (error reds, approval --accent). Motion is purposeful and minimal: items animate out on resolve and rise on re-rank, swipe reveals are spring-eased, pull-to-refresh has a satisfying snap. Nothing pulses or demands attention except genuine pinned urgency. Generous whitespace, big legible type, thumb-friendly — it should feel like a well-made mobile app, not a dashboard crammed onto a phone.

19. Strengths

• Best-in-set return-use & notification loop (§9): pinned-top + push + pull-to-refresh is purpose-built for the closed-laptop-checked-from-phone aha moment — the product’s defining promise.
• One-handed, sub-minute triage. Swipe-to-approve / swipe-to-stop + big targets make the common monitor→approve loop a glance and a thumb-flick.
• Always-right-first. Priority feed means the user never scans or hunts; the top of the feed is the answer to “what needs me?” — and failures share that same privileged zone.
• Fast known-recipe launch. Template quick-start matches the persona’s actual launch behavior (mostly re-runs), eliminating per-launch form-filling.
• Honest about the phone. Read-mostly mobile terminal + explicit desktop handoff refuses to fake deep work on a small screen; it routes to the right device instead of degrading.
• Lowest cognitive load. One column, one home, one sheet — recognition over recall (the inverse of V4); approachable where V1 is intimidating.
• Clean degradation. Loses connection / push gracefully (last-known + pull-to-refresh) without breaking the triage value.

20. Risks & Failure Modes (with mitigations)

• Weak dense-desktop multitasking. A single centered feed underuses a big monitor; the power user watching 12 agents at the desk is better served by V1’s split-pane/table. Mitigation: the optional desktop second pane (§17) keeps the feed in view while reading one agent; and V5 is explicitly not pitched as the desktop-power variation — that contrast is owned by V1. If empirical eval shows desktop multitasking matters more than assumed, that’s a signal to favor a sibling, not to bloat V5.
• Feed reordering volatility. As statuses change, items re-rank and the pinned zone reshuffles — motion can feel unstable, and an item the user was about to tap can move. Mitigation: (a) animate re-ranks smoothly so position changes are trackable, not teleports; (b) debounce re-sorts (small settle delay) so rapid status flapping doesn’t thrash the list; (c) a brief “touch-lock” on the item under the user’s finger so an active swipe target can’t slip away mid-gesture; (d) the pinned/stream seam is stable even as within-zone order changes.
• Template-launch inflexible for novel prompts. Recipe-first is great for re-runs but friction for a genuinely new task. Mitigation: “New from scratch” is always one tap away (secondary in the sheet); the tokenized prompt field handles the common “same recipe, new path/branch” case inline; and “Save as recipe” turns any from-scratch launch into a future fast path, so the recipe library grows toward the user’s real work.
• Mobile push unreliability (iOS Safari). The return-use loop leans on push; Web Push is platform-spotty (flow-map Open Q #3). Mitigation: pinned-zone + pull-to-refresh deliver full triage value on manual open even with zero push; install banner is suppressed (not nagged) when push is unavailable; alternate channels are an upstream notification-policy decision V5 defers to.
• Read-mostly terminal may frustrate users who want to type on mobile. Mitigation: this is a deliberate, signposted tradeoff (the “open on desktop” button is prominent and fast); it directly de-risks the terminal-latency open question rather than betting the phone on sub-100ms echo. If eval shows strong demand for mobile typing, that’s input to the device-handoff branch, not a reversal of V5’s posture.
• Above-the-fold real estate pressure. A burst of many simultaneous approvals/errors can overflow the pinned zone. Mitigation: pinned zone caps height and internally scrolls with a “+N more need you” affordance, so the most-urgent stay visible and the rest are one scroll away.

21. Implementation Complexity

Rough estimate: medium (consistent with the brief’s complexity column).

• Cheaper than baseline in places: one-column feed is simpler layout than V2’s responsive grid or V1’s dense sortable/filterable table; no split-pane state management; one detail surface (folded S5/S6) instead of two screens + a Mode toggle.
• Where the cost concentrates:
  • Swipe-gesture layer (revealable, reversible, optimistic, confirm-gated, with desktop button fallbacks) — the trickiest custom interaction; needs careful touch handling + the touch-lock/debounce reordering work (§20).
  • Animated priority re-ranking of a live WebSocket-driven list (smooth, debounced, stable seam) — non-trivial list-animation engineering.
  • PWA + Web Push (service worker, push subscription, deep-link routing, install prompt, graceful no-push degradation) — V5 leans hardest on this of any variation, so it carries that cost.
  • Recipe/template model (save, tokenize, prefill, edit) — modest new data model + UI.
  • Tool-adaptive folded detail with read-mostly mobile terminal + desktop handoff — the xterm.js/WebSocket integration is shared work, but V5 adds the read-mostly mode and the handoff wiring (which leans on the device-handoff branch).
• Net: no single hard subsystem (no IDE/code-server, no dense data-grid virtualization), but several medium-effort interaction polishes (swipe, re-rank animation, push) that must feel good or the whole premise falls flat — so the risk is in interaction quality, not architectural difficulty.

22. Prototype Scope

For a tangible, evaluable prototype (feeding /uat --variant-evaluation and /ui-interview):

In scope (build):

• S3 feed at mobile breakpoint with a realistic mixed fleet (≥1 error, ≥1 approval, several running w/ live-ish stdout, some idle) showing the pinned/stream split and sort.
• Swipe interactions on pinned items — swipe-to-approve, swipe-to-stop, with reveal + confirm + animate-out + re-rank.
• Pull-to-refresh gesture (can mock the resync).
• S4 template quick-start sheet with ≥3 seed recipes, recipe→prefill, tokenized-field edit, Start → new “starting” feed item appears; plus the secondary “new from scratch” entry.
• Full-screen detail sheet for both a CLI tool (terminal-primary, read-mostly, with the “open on desktop” button) and an API-native tool (structured) to demonstrate tool-adaptive folding with no Mode toggle.
• Bottom nav (Feed/Launch/Approvals/Settings) and at least the desktop centered-feed + optional second pane layout to show the responsive posture gradient.
• One failure case (e.g., agent crash pinning to top + connection banner) to demonstrate §10.

Out of scope (stub / reference only): real diff viewer & deep approval logic (approval branch), QR/deep-link token plumbing (device-handoff), recap S8, diff/merge S9, settings S10 internals, real backend/WebSocket (mock the stream), real auth, code-server/IDE (explicitly excluded). Push can be simulated rather than wired to a real push service.

Fidelity: static-HTML/CSS interactive prototype (per /prototype for UI projects) with mocked state transitions sufficient to feel the glance→swipe→launch loop — interaction feel is the thing being evaluated, so the swipe/refresh/re-rank gestures should be genuinely interactive even if data is faked.

23. Readiness Signal for /ui-interview

This spec is build-grade and ready for /ui-interview [v5-glanceable-stream] (or for serial prototyping ahead of /uat --variant-evaluation → /consolidate-variations). It is decided and unambiguous on:

• ✓ Board representation (prioritized vertical feed; pinned/stream split; reworked sort).
• ✓ Orchestrate↔deep-work connection (feed → full-screen sheet; gravity-back-to-feed).
• ✓ Launch affordance (duplicate-from-template quick-start sheet; recipe model; from-scratch secondary).
• ✓ Folded + tool-adaptive detail with no Mode A/B toggle; mobile read-mostly terminal + desktop handoff; desktop interactive.
• ✓ Device posture (mobile-first; tablet centered column; desktop centered feed + optional pane).
• ✓ Navigation, components, swipe/tap behavior, density, three-breakpoint responsive behavior, visual tone.
• ✓ Return-use/notification, failure recovery, sibling boundaries, complexity, prototype scope.
• ✓ Single-user N/A items stated, not invented (sharing, collaboration, permissions).
• ✓ Bounding open questions honored (terminal latency → read-mostly+handoff; stdout-parsing → chrome degrades to raw tail; code-server/IDE → out of scope by deliberate choice).

Open items intentionally deferred to /ui-interview (not blockers): exact type ramp / spacing tokens, precise swipe-threshold and animation-timing values, final glyph/color semantics within the dark palette, the exact pinned-zone height cap, and the precise bottom-nav target set (3 vs 4) — all visual/interaction-tuning decisions appropriate to the UI interview, not the UX variation.

Cross-variation note for /consolidate-variations: V5’s distinctive, cherry-pickable elements are (1) the pinned-zone return-use loop, (2) swipe-to-approve/stop, (3) the duplicate-from-template launch, and (4) the read-mostly-mobile-terminal + desktop-handoff pattern — any of which could be lifted into a consolidated direction even if the full feed model isn’t the chosen spine.

Build all five variations serially, in full — this is the user’s stated preference. We do not build a subset first and gate the rest; each variation gets a complete, evaluable build before moving to UAT. (Per §6 each spec carries its own §22 Prototype Scope defining a build-grade, evaluable prototype.)

Route-based experiments (one per variation)

Each variation is built as its own route experiment under a dedicated path, so the five live side by side in one app shell without forking the repo:

Rules for the experiments:

• Keep shared production infrastructure out of these routes. The experiments share the tech stack + design system (per CLAUDE.md) and may share mock data/state fixtures, but production board/agent infra is not wired into /experiments/*. Each route is a self-contained, mock-backed prototype sufficient to feel its interaction model (mock WebSocket/stdout, mock approvals, mock launch).
• These are route experiments, NOT git branches. All five live on the primary branch under /experiments/*; there is no per-variation feature branch. (The agent-team parallel-write-lane exception in CLAUDE.md does not apply — this is sequential, single-author work.)
• They do not (yet) imply separate product paths. Because no variation has been chosen and these are throwaway comparison routes, research/.progress.yaml is not updated. Progress tracking happens only when a direction is locked (§9) and promoted into the real product surface.

The criteria a winner is judged on are fixed now, before evaluation, so selection is evidence-driven rather than post-hoc rationalized. Each variation is scored against the same set during /uat --variant-evaluation:

Device posture is not a pre-decided winner: it is one of the criteria above, scored empirically across the set. A variation that wins on glanceability but loses on cross-device fit is a consolidation signal, not an automatic disqualifier.

When a direction is chosen, record it as a decision (not a vague preference) by completing this checklist. The output becomes a dated decision entry referenced by /consolidate-variations and the eventual /ui-interview.

• ☐ Chosen variation — which of V1–V5 is the spine (or “consolidated hybrid of …”).
• ☐ Why — the evidence from §8 criteria that decided it (cite the UAT findings, not gut alone): which criteria it won, which it lost, and why the wins outweigh the losses for this persona/surface.
• ☐ Cherry-picked elements from losers — specific elements to lift from non-chosen variations (e.g. V5’s pinned-zone + swipe-to-approve, V1’s split-pane fleet-visibility, V3’s spatial error/waiting distinction, V4’s ⌘K accelerator), each with where it grafts onto the chosen spine.
• ☐ Explicitly rejected — what is not carried forward and why (e.g. “Mode A/B user toggle — rejected, folded tool-adaptive stands”; “desktop-primary as global default — rejected”; “Kanban card-motion — rejected as too unstable”). Rejections are as load-bearing as selections.
• ☐ Posture decision — the resolved device-posture stance for the chosen direction (the axis that was deliberately left empirical).
• ☐ Open questions still live — which bounding questions (terminal latency, stdout-parsing reliability, push reliability, code-server ROI) remain unresolved and are carried into /ui-interview / build.
• ☐ Flow-map amendment status — confirm the §3 amendment (merge S5/S6, drop Mode A/B) is accepted / pending / rejected by the flow-map owner.
• ☐ Sign-off — recorded owner + date; the decision is logged (decision record / tasks/), and only then is research/.progress.yaml updated to reflect a chosen product path.

Per the variant-evaluation skill, prepare the following before running UAT against the five built route experiments:

• ☐ Target task per variant (identical across all five) — a single representative task run in each, e.g.: “From a 10-agent fleet: triage the errors and approvals to the top, approve the clear ones, drill into one crashed agent and read its failure, then fan out a parallel agent (Path C) — all without losing track of the fleet.” Same task, five surfaces.
• ☐ Success criteria — task completed; next blocker found in <Ns; parallel agent launched in <Ns; user could read fleet status at 8–12 agents without getting lost; drill-in did/didn’t lose board context.
• ☐ Side-by-side comparison questions — Which surface let you find the next thing that needs you fastest? Which felt best at 12 agents? Where did you lose the fleet? Which launch felt fastest / most natural? Which would you actually want on your phone vs your desktop? Which felt intimidating or hid capability?
• ☐ Evidence to capture — screenshots of each variant at the same fleet state; time-to-complete the target task per variant; explicit friction points (where the user paused, hunted, mis-clicked); accept/reject signals per variant (the §23 readiness signal in each spec) and per element.
• ☐ Tradeoffs to notice — density vs glanceability (V1↔V2), motion/instability cost (V3, V5 re-rank), discoverability cost (V4 palette), route-context-loss (V2), mobile degrade vs mobile-first (V1↔V5), launch velocity vs flexibility (V5 template).
• ☐ Readiness for /consolidate-variations — all five built and run through the same task; evidence captured per the above; a clear pattern of wins/losses against §8 criteria; at least a tentative answer to “spine + cherry-picks” so consolidation has material. If the evaluator wants element A from one variant and element B from another, that is the expected /consolidate-variations input, not a failure.

• Parent user flow: monitoring-start (Happy Path steps 3–6 + Path C “Parallel Sprint”) of design/user-flow-personal-workstation.md.
• UX variation branch ids (this plan): v1-operator-console, v2-card-mosaic, v3-kanban-pipeline, v4-command-first, v5-glanceable-stream.

Sibling flow / variation dependencies

These siblings own deep stories that the monitoring-start variations only border — they are referenced, not redesigned here:

• approval (Path B + S7) — owns the deep mobile-approval experience: rich diff viewer, risk assessment, modify/reject-with-reason, batch/queue policy, push-to-approval deep links. V5’s swipe-to-approve and pinned approval items, and every variation’s inline approval, hand off into this branch’s S7 surface for anything past a one-swipe yes/no.
• device-handoff (Paths E + F, incl. qr-handoff) — owns cross-device continuity and the QR-handoff story: QR generation, one-time token, pre-authenticated deep links, recap (S8) timeline. Every variation’s “Open on Mobile” / “open on desktop” affordance is an entry point into this branch, not a re-implementation. V5 Glanceable Stream only borders the deep mobile-approval and QR-handoff stories; it surfaces and routes, it does not own them.
• Other siblings reached as handoffs: recovery (Path D — error remediation), diff-review (S9 — “Review diffs”), settings (Path G — S10 credential/tool config), onboarding (Path A — first-run provisioning).

Next step (gated until approval)

Per the serial-build plan, all five variations are built before any /ui-interview, then /uat --variant-evaluation → /consolidate-variations. When a /ui-interview candidate is taken to visual mockup:

Recommended first /ui-interview candidate (pending approval): v2-card-mosaic. As the baseline/control closest to the approved flow-map, it is the lowest-risk anchor for the comparison — interviewing it first establishes the control reference against which the other four are measured. (This recommendation does not change the serial-build order: all five are built first.) Downstream routing language stays gated until this review page is approved via compiled response YAML.