# workflow popup prototypes > **Historical reference, superseded for new development:** These mocks describe the legacy `workflow` extension and custom TUI. New feature work uses the model-invoked [`develop-workflow` skill](../../skills/develop/develop-workflow/SKILL.md) under [ADR 0006](../adr/0006-skill-led-development-workflow-04SEP2026.md). Retain them as prototype evidence. **Status:** Historical direction C evidence These static terminal frames compare popup directions for `/workflow`. They are prototype evidence, not production screenshots or manual validation of the implemented extension. All variants use Pi theme tokens, keyboard-visible focus, one border at most, and no animation. Representative run: `workflow-usability-resume`, waiting at Plan Approval after Discover and Design. ## A. Centered compact modal A small modal preserves the surrounding conversation and keeps one decision in focus. ```text ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ ╭─ workflow ──────────────────────────────╮ │ │ │ workflow-usability-resume │ │ │ │ WAITING · Plan Approval · revision 12 │ │ │ │ │ │ │ │ ✓ Discover ✓ Design · Prototype │ │ │ │ · Implement · Verify · Review │ │ │ │ │ │ │ │ > Review plan │ │ │ │ Approve plan │ │ │ │ Request revision │ │ │ │ Close │ │ │ │ │ │ │ │ ↑↓ navigate enter select esc close │ │ │ ╰─────────────────────────────────────────────╯ │ │ │ └──────────────────────────────────────────────────────────────────────┘ ``` Strengths: - Minimal visual interruption. - Familiar one-step prompt behavior. - Low chrome and clear focus. Weaknesses: - Long plans and detailed run state require repeated modal replacement. - Context disappears quickly as the interaction deepens. - Poor fit for browsing artifacts or transcripts. ### A at 60 columns ```text ╭─ workflow ───────────────────────╮ │ usability-resume · WAITING │ │ Plan Approval · r12 │ │ │ │ > Review plan │ │ Approve plan │ │ Request revision │ │ Close │ │ │ │ ↑↓ enter esc │ ╰─────────────────────────────────────╯ ``` ## B. Near-full-screen workspace A stable workspace keeps the run list, selected run, progress, and actions visible together. ```text ╭─ workflow ────────────────────────────────────────────────────────────────╮ │ Runs │ workflow-usability-resume WAITING │ │ │ feature/workflow-usability-resume · r12 │ │ > usability-resume │ │ │ auth-cleanup │ Progress │ │ cache-audit │ ✓ Discover ✓ Design · Prototype · Implement │ │ │ · Verify · Review │ │ │ │ │ │ Open Gate │ │ │ Plan Approval │ │ │ Review the implementation plan before work begins. │ │ │ │ │ │ > Review plan │ │ │ Approve plan │ │ │ Request revision │ │ │ Browse artifacts │ │ │ Close │ │ │ │ │ ↑↓ run tab focus │ ↑↓ action enter select esc back │ ╰──────────────────────────────────────────────────────────────────────────────╯ ``` Strengths: - High information density with stable spatial context. - Fast comparison between several active runs. - Actions and state remain visible together. Weaknesses: - The permanent left pane spends space on uncommon multi-run comparison. - Focus management and responsive collapse are more complex. - At 80 columns the content pane becomes cramped; below 80 it must become a different UI. ### B at 80x24 ```text ╭─ workflow ────────────────────────────────────────────────────────────────╮ │ Runs │ usability-resume · WAITING · r12 │ │ > usability │ ✓ Discover ✓ Design · Prototype │ │ auth-cleanup │ · Implement · Verify · Review │ │ cache-audit │ │ │ │ Plan Approval │ │ │ > Review plan │ │ │ Approve plan │ │ │ Request revision │ │ │ Browse artifacts │ │ │ │ │ tab focus │ ↑↓ action enter select esc back │ ╰──────────────────────────────────────────────────────────────────────────────╯ ``` ### B at 60 columns The workspace must collapse to a single run-detail pane. The run list becomes a prior drill-down view, effectively converging on direction C. ## C. Drill-down overlays with dedicated readers Direction C uses shallow browser-style navigation. Each overlay does one job. Escape always returns one level. ### C1. Run list popup ```text ╭─ workflow ─────────────────────────────╮ │ > usability-resume WAITING Plan Approval│ │ auth-cleanup RUNNING Implement │ │ cache-audit DONE report ready │ │ │ │ ↑↓ navigate enter open esc close │ ╰────────────────────────────────────────────╯ ``` ### C2. Run detail popup ```text ╭─ usability-resume ───────────────────────────────────╮ │ WAITING · Plan Approval · revision 12 │ │ │ │ ✓ Discover ✓ Design · Prototype · Implement │ │ · Verify · Review │ │ │ │ > Review plan │ │ Record Gate Decision │ │ Browse prototype evidence │ │ Browse Assignment transcripts │ │ Show worktree path │ │ │ │ ↑↓ navigate enter select esc runs │ ╰──────────────────────────────────────────────────────╯ ``` ### C3. Plan reader at wide width The reader uses the whole overlay. The terminal edge is the outer frame, so there is no decorative full-screen border. The left outline tracks the heading containing the top visible document line. ```text workflow plan · usability-resume line 42/216 Outline Plan ───────────────────────────── ───────────────────────────────────────────── workflow usability update # workflow usability update plan Locked decisions > Implementation phases ## Implementation phases Prototype overlays Session lifecycle ### 2. Session lifecycle and recovery Worktree safety Popup TUI - Route the dashboard's fresh-session action Progress widget through the existing continuation path. Design regression Acceptance criteria - Atomically rotate lease and context owners during absent/dead adoption. Primary files: dashboard.ts, context-transition.ts, continuation.ts, engine.ts, and focused tests. ↑↓ scroll pgup/pgdn page home/end document esc back ``` ### C3 at 80x24 ```text workflow plan · usability-resume row 42/216 Outline Plan ────────────────────── ───────────────────────────────────────────── Locked decisions ## Implementation phases > Implementation Prototype overlays ### 2. Session lifecycle and recovery Session lifecycle - Route the dashboard's fresh-session action Worktree safety through the existing continuation path. Popup TUI Progress widget - Atomically rotate lease and context owners Acceptance criteria during absent/dead adoption. ↑↓ scroll pgup/pgdn page home/end document esc back ``` ### C3 at 60 columns The outline hides and the document becomes the only pane. The current heading remains visible in the header. ```text workflow plan · Implementation phases · row 42/216 ## Implementation phases ### 2. Session lifecycle and recovery - Route the dashboard's fresh-session action through the existing continuation path. - Atomically rotate lease and context owners during absent/dead adoption. ↑↓ scroll pgup/pgdn page home/end document esc back ``` ### C3 at 47x11 ```text terminal too small workflow plan needs 48x12 current terminal is 47x11 resize the terminal or press esc ``` Strengths: - Each screen has one dominant task and a complete local keymap. - Best responsive behavior because narrow layouts remain single-pane. - Long plans and transcripts get dedicated virtualized readers. - The shallow stack preserves context without permanent side-panel cost. Weaknesses: - Comparing several runs takes more navigation than direction B. - Back-stack state and overlay focus/disposal require careful implementation. ## Persistent progress widget The widget is independent of the selected popup direction and stays above Pi's editor while the newest attached run is active. Standard: ```text workflow usability-resume DESIGN 2/6 Gate: Plan Approval ``` Narrow: ```text workflow usability-resume DESIGN 2/6 ``` Terminal runs disappear rather than leaving a stale receipt above the editor. ## Recommendation Use direction C. It has one border only on bounded popup cards, no redundant frame around the full-screen reader, keyboard-visible selection, and the most truthful 80-column and 60-column degradation. Direction B spends too much space on multi-run comparison, while direction A does not provide enough stable space for plans and evidence. ## Production mapping The accepted direction maps to `extensions/workflow/tui.ts` and `dashboard.ts`. The implementation uses popup overlays for bounded selections and text entry, then switches to the full-screen reader for verified plans and retained evidence. `progress.ts` owns the separate one-line widget. Pure renderer tests cover the wide, 80-column, 60-column, and below-48x12 contracts; interactive Pi validation remains a separate manual step. ## Interaction contract - Arrow keys navigate every selection surface; Enter selects; Escape cancels or returns one level. - Page Up/Page Down and Home/End apply only to long-document readers. - Text inputs use Pi's `Input` or `Editor` components and propagate focus for IME positioning. - The current selection uses position plus selected background or reverse video, never color alone. - TUI overlays are never opened in RPC, print, or JSON mode. - Every rendered line is truncated or wrapped by terminal cell width rather than JavaScript string length. - No continuously repainting animation is used.