285 lines
14 KiB
Markdown
285 lines
14 KiB
Markdown
# workflow popup prototypes
|
|
|
|
**Status:** Direction C accepted
|
|
|
|
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.
|