feat: package Pi extensions as Bun workspaces
This commit is contained in:
@@ -0,0 +1,284 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user